k8shell CLI

The k8shell CLI is the primary command-line tool for interacting with a k8shell api-server. It lets you authenticate, manage workspaces, inspect users, and review session history — all from the terminal. The CLI stores its configuration in ~/.config/k8shell/config.yaml and supports multiple named contexts so you can switch between different server environments without re-authenticating.

Commands

k8shell connects to a k8shell server and provides commands for managing
its resources.

Run 'k8shell --help' on any command to see its available options.

Usage:
  k8shell [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  context     Manage contexts
  help        Help about any command
  login       Login via browser and save credentials to a context
  session     Manage sessions
  user        Manage users
  workspace   Manage workspaces

Flags:
      --config string    config file (default: ~/.config/k8shell/config.yaml)
  -c, --context string   override the active context
      --debug            print request and response headers to stderr
  -h, --help             help for k8shell
      --insecure         skip TLS certificate verification
      --json             output as JSON
      --no-ansi          disable ANSI color output
  -w, --wrap             allow lines to wrap beyond terminal width

Use "k8shell [command] --help" for more information about a command.

Logging in

k8shell authenticates using a Personal Access Token (PAT). Rather than creating a PAT manually, the CLI requests one automatically: it contacts the server, presents the available identity providers, and opens a browser so you complete the OAuth flow. Once login succeeds, the PAT is created on the server and saved to a local context.

$ k8shell login --server https://app.k8shell.io
Available login providers:
  1) github
  2) gitlab
Select provider [1]: 1
Opening browser for login...
Waiting for login to complete... done.
Logged in as bruckins. Context "app.k8shell.io-e2edc0ff" saved and set as active.

info

By default, the CLI enforces one context per server — running k8shell login for a server that already has a context will fail with an error. Use --ignore to bypass this restriction, which allows multiple contexts for the same server (for example, different usernames on the same instance).

Contexts

A context stores a server URL and the associated credentials. You can have multiple contexts — for example, one per environment — and switch between them as needed.

# list all configured contexts
k8shell context list

# switch the active context
k8shell context use prod

# remove a context
k8shell context delete staging

If you have a PAT already, you can add a context without going through the browser:

k8shell context add prod --server https://app.k8shell.io --token <pat>

Omitting --token prompts for it securely. Any command accepts -c <name> to use a different context without changing the active one.

Configuration file

Contexts are stored in ~/.config/k8shell/config.yaml:

current-context: app.k8shell.io
contexts:
  - name: app.k8shell.io-e2edc0ff
    server: https://app.k8shell.io
    token: k8sh_AQlQvU04ENnZTaB8PCBguOrIeHVMyEp0JdO4FHB8RRE
    username: bruckins
    tokenHash: 38c57dcaa2302f293cb0149380c89db98f3f9c90caa1f28df60f9f46349a2152

username is retrieved automatically after login or context add via the profile API endpoint. tokenHash is a SHA-256 hash of the server name and username, used internally to identify the context.

Global flags

These flags apply to all commands:

Flag	Description
-c, --context	Override the active context for this command.
--json	Output results as JSON.
--debug	Print request and response headers to stderr.
--insecure	Skip TLS certificate verification.
--no-ansi	Disable ANSI color output.
-w, --wrap	Allow output lines to wrap beyond terminal width.
--config	Use an alternate config file (default: ~/.config/k8shell/config.yaml).

Shell completion

k8shell can generate shell completion scripts for bash, zsh, fish, and PowerShell.

# bash (add to ~/.bashrc)
source <(k8shell completion bash)

# zsh (add to ~/.zshrc)
source <(k8shell completion zsh)

# fish
k8shell completion fish > ~/.config/fish/completions/k8shell.fish