CLI Quickstart

The Kaiten CLI lets you manage customers, instances, licenses, entitlements, feature flags, and more from the terminal.

Prerequisites

A running Kaiten stack (Kaiten Cloud or self-hosted)
A service account with an API token (ksh_*)
Go 1.25+ — the CLI is installed with go install

If you do not have a token yet, the quickstart shows how to create a service account and generate one.

Setup

Install the CLI

go install github.com/kaitencloud/cli/cmd/kaiten@latest

Verify the installation:

kaiten version

The base URL is https://app.kaiten.sh/api on Kaiten Cloud and http://localhost:6060/api on a local Community Edition stack. It keeps its /api prefix: the CLI appends resource paths to it as given.

Option A — Config file (recommended)

kaiten config set base-url https://app.kaiten.sh/api
kaiten config set auth-token ksh_your_token_here

Configuration is saved to config.yaml in your user configuration directory — ~/.config/kaiten/ on Linux, ~/Library/Application Support/kaiten/ on macOS, %AppData%\kaiten\ on Windows — readable by you only. kaiten config view prints the exact path.

Option B — Environment variables

export KAITEN_BASE_URL=https://app.kaiten.sh/api
export KAITEN_AUTH_TOKEN=ksh_your_token_here

The quickstart exports the same two values as KAITEN_API and KAITEN_TOKEN for its curl calls; the CLI reads its own names.

Option C — Inline flags (per-command)

kaiten customers list --base-url http://localhost:6060/api --auth-token ksh_your_token_here

Priority order: CLI flags > environment variables > config file.

Verify connectivity

kaiten doctor

kaiten doctor lists your instances to prove that the API answers and accepts the token, so the token needs read:instances. On success it prints base_url, the masked auth_token, instances_count, and status: ok.

Run your first commands

# List all customers
kaiten customers list

# Get a specific customer, as the API returns it
kaiten customers get sakura-tokyo --output json

# List instances as JSON
kaiten instances list --output json

# View your current configuration
kaiten config view

Configuration reference

Source	Base URL	Auth Token	Output Format
CLI flag	`--base-url`	`--auth-token`	`--output`
Environment variable	`KAITEN_BASE_URL`	`KAITEN_AUTH_TOKEN`	`KAITEN_OUTPUT`
Config file key	`base_url`	`auth_token`	`output`

Config file location: config.yaml in your user configuration directory — ~/.config/kaiten/ on Linux, ~/Library/Application Support/kaiten/ on macOS, %AppData%\kaiten\ on Windows. kaiten config view prints the exact path.

Output formats

Format	Flag	Default for	Description
`table`	`--output table`	`list` commands	Human-readable columnar output
`yaml`	`--output yaml`	Single-resource commands	YAML document
`json`	`--output json`	—	JSON document

To read a resource exactly as the API returns it — the same field names, the same values — pass --output json.

Where to go next

Command Reference lists every command, flag, and input format.