CLI Reference

August 9, 2026 · View on GitHub

Every kt command, subcommand, and flag. The CLI is the operator-facing surface over the framework: starting creatures, starting terrariums, managing packages, configuring LLMs, serving the web UI, and searching saved sessions.

For the mental model of creatures, terrariums, and privileged nodes, read concepts/boundaries. For task-oriented paths, see guides/getting-started and guides/creatures.

Entry points

kt: installed console script.
python -m kohakuterrarium: equivalent.
Invoked with no subcommand (e.g. from a Briefcase double-click), kt starts the desktop app automatically.

Global flags

Flag	Purpose
`--version`	Print version, install source, package path, Python version, and git commit.
`--verbose`	With `--version`, also print `$VIRTUAL_ENV`, executable, and git branch.

Core commands

`kt run`

Run a single creature.

kt run <agent_path> [flags]

Positional:

agent_path: local folder containing config.yaml, or a package reference like @kt-biome/creatures/swe.

Flags:

Flag	Type	Default	Description
`--log-level`	`DEBUG\|INFO\|WARNING\|ERROR`	`INFO`	Root logger level.
`--log-stderr`	`auto\|on\|off`	`auto`	Mirror logs to stderr. `auto` = on when the I/O mode is not cli/tui (e.g. `plain`, `stdout`, `custom`, `package`); `off` = never; `on` = always.
`--session`	path	auto	Session file to write; absolute or name under `~/.kohakuterrarium/sessions/`.
`--no-session`	flag	(none)	Disable session persistence entirely.
`--llm`	str	(none)	Override LLM profile (e.g. `gpt-5.4`, `claude-opus-4.7`). Accepts a variation selector; see configuration reference.
`--mode`	`cli\|plain\|tui`	auto	Interaction mode. Defaults to `cli` on TTY, `plain` otherwise.

Behaviour:

@package/... paths resolve to ~/.kohakuterrarium/packages/<pkg>/..., following .link pointers for editable installs.
A session is auto-created under ~/.kohakuterrarium/sessions/ with extension .kohakutr unless --no-session is set.
On exit, prints a kt resume <name> hint.
In Rich CLI mode, Ctrl+C interrupts the current turn; when idle, press Ctrl+C twice (or Ctrl+D / /exit) to shut down cleanly.

`kt resume`

Resume a prior session. Agent vs terrarium is auto-detected from the session file.

kt resume [session] [flags]

Positional:

session: name prefix, full filename, or full path. Omit for an interactive picker of the 10 most-recent sessions.

Flags:

Flag	Type	Default	Description
`--pwd`	path	session's stored cwd	Override working directory.
`--last`	flag	(none)	Resume the most-recent session without prompting.
`--log-level`	as `kt run`
`--log-stderr`	as `kt run`	`auto`	Mirror logs to stderr.
`--mode`	as `kt run`		Terrarium sessions force `tui`.
`--llm`	str		Override LLM profile for the resumed session. Supports the variation-selector shorthand.

Behaviour:

.kohakutr and legacy .kt extensions are accepted and stripped.
Prefix matches that are ambiguous trigger a picker.

`kt list`

List installed packages and local agents.

kt list [--path agents]

Flag	Type	Default	Description
`--path`	str	`agents`	Local folder to scan in addition to installed packages. Mainly useful when the cwd is a project with its own `agents/` folder; installed packages always appear regardless of `--path`.

`kt info`

Print name, description, model, tools, sub-agents, and files for a creature config.

kt info <agent_path>

Terrarium

`kt terrarium run`

Run a multi-agent terrarium.

kt terrarium run <terrarium_path> [flags]

Positional:

terrarium_path: YAML file or @package/terrariums/<name>.

Flags:

Flag	Type	Default	Description
`--log-level`	as `kt run`
`--seed`	str	(none)	Prompt to inject into the seed channel at startup.
`--seed-channel`	str	`seed`	Channel to receive `--seed`.
`--observe`	list of channel names	(none)	Channels to observe (plain/log mode).
`--no-observe`	flag	(none)	Disable observation entirely.
`--session`	path	auto	Session file path.
`--no-session`	flag	(none)	Disable persistence.
`--llm`	str	(none)	Override LLM profile for every creature (and root).
`--mode`	`cli\|plain\|tui`	`tui`	UI mode.

Behaviour:

tui mounts multi-tab view: root + each creature + each channel.
cli mounts root (if present) or the first creature under RichCLI.
plain streams observed channel messages to stdout.

`kt terrarium info`

Print terrarium name, creatures, listen/send channels, and channel list.

kt terrarium info <terrarium_path>

Packages

`kt install`

Install a package from a git URL or local path.

kt install <source> [-e|--editable] [--name <name>]

Flag	Type	Default	Description
`-e`, `--editable`	flag	(none)	Write a `<name>.link` pointing at the source instead of copying.
`--name`	str	derived from URL/path	Override installed package name.

<source> may be:

A git URL (cloned into ~/.kohakuterrarium/packages/<name>).
A local directory (copied, or linked with -e).

`kt uninstall`

Remove an installed package.

kt uninstall <name>

`kt update`

Update git-backed packages. Skips editable and non-git packages.

kt update [target] [--all]

Flag	Type	Description
`--all`	flag	Update every git-backed package.

`kt edit`

Open a creature or terrarium config in $EDITOR (falls back to $VISUAL, then nano).

kt edit <target>

target accepts package refs (@pkg/creatures/name) and local paths.

Configuration: `kt config`

`kt config show`

Print every config file path used by the CLI.

`kt config path`

Print the path for one of: home, llm_profiles, api_keys, mcp_servers, ui_prefs.

kt config path [name]

`kt config edit`

Open a config file in $EDITOR. Defaults to llm_profiles when no name is given.

kt config edit [name]

`kt config provider` (alias: `kt config backend`)

Manage LLM providers (backends).

`kt config provider list`

Show Name, Backend Type, Provider identity, Native tools, and Base URL for each provider.

`kt config provider add`

Interactive. Prompts for backend type, base URL, api_key_env, a provider identity (provider_name), and a checkbox-style list of provider-native tools to expose. The prompt offers openai, anthropic, and codex; stored backend types use those same canonical values.

kt config provider add [name]

kt config provider add and kt config provider edit call the same interactive path; the only difference is that edit requires a positional name and pre-fills the existing values.

`kt config provider edit`

Same fields as add, pre-filled from the current entry.

kt config provider edit <name>

`kt config provider delete`

kt config provider delete <name>

`kt config llm` (aliases: `kt config model`, `kt config preset`)

Manage LLM presets.

`kt config llm list`

Show Name, Provider, Model, a Groups column (comma-separated variation group names, if any), and a Default marker. By default lists only user-defined presets.

Flag	Type	Default	Description
`--all`	flag	(none)	Also include every built-in preset. Rows are grouped (User presets / Built-in presets); the Legend marks which entries have API key / OAuth configured.

`kt config llm show`

Print the full preset: name, provider, backend type, model, max_context / max_output, base URL, api_key_env, temperature, reasoning effort, service tier, current variation selections (if any), the preset's declared variation groups with selector examples (e.g. claude-opus-4.7@reasoning=xhigh), and extra_body.

kt config llm show <name>

`kt config llm add`

Interactive. Prompts whether to mark the new preset as the default (defaults to No).

kt config llm add [name]

`kt config llm edit`

kt config llm edit <name>

`kt config llm delete`

kt config llm delete <name>

`kt config llm default`

Without argument, print the current default. With name, set it.

kt config llm default [name]

`kt config key`

Manage stored API keys.

`kt config key list`

Columns: provider, api_key_env, source (stored/env/missing), masked value.

`kt config key set`

Save an API key to ~/.kohakuterrarium/api_keys.yaml. Prompts (masked) if value is omitted.

kt config key set <provider> [value]

`kt config key delete`

Clear the stored key (the provider entry itself stays intact).

kt config key delete <provider>

Alias of kt login. See Auth.

`kt config mcp`

Manage the global MCP server catalog (~/.kohakuterrarium/mcp_servers.yaml).

list: show file path and server inventory.
add [name]: interactive. Prompts for transport (stdio/streamable_http/http), command, args JSON, env JSON, URL.
edit <name>: interactive edit.
delete <name>: remove entry.

`kt config drive`

Manage the Drive runtime settings (~/.kohakuterrarium/drive-settings.yaml) through the Studio settings façade. Save and apply are distinct — the plain CLI owns no running engine, so apply reports validity, not a live swap.

kt config drive {show | registrations | set <field> <value> | apply}

show: runtime enabled state + tuning + per-registration enabled state.
registrations: list installed Drive registrations and their enabled / load status.
set <field> <value>: set a runtime field or toggle a registration, then save (CAS-checked). Field forms: a runtime field (enabled true, max_active_per_creature 8) or registration:<name> on|off (e.g. registration:generic on).
apply: validate that the saved settings resolve; reports applied_live / restart_required / rejected (a running server picks up a valid file on restart).

Auth

Authenticate with a provider.

kt login <provider>

For codex backend with no base_url: OAuth device-code flow. Tokens stored at ~/.kohakuterrarium/codex-auth.json. With a base_url set (custom OpenAI-Responses endpoint), it prompts for an API key instead.
For API-key backends: prompts (masked) and saves to ~/.kohakuterrarium/api_keys.yaml.

Models

`kt model`

Thin back-compat wrappers over kt config llm. Prefer the kt config llm forms in new docs; kt model stays as a one-liner alias.

kt model list
kt model default [name]
kt model show <name>

Memory and search

`kt embedding`

Build FTS and vector indices for a saved session. <session> accepts a name prefix, full filename, or path; the legacy .kt extension is also recognized in addition to .kohakutr.

kt embedding <session> [--provider ...] [--model ...] [--dimensions N]

Flag	Type	Default	Description
`--provider`	`auto\|model2vec\|sentence-transformer\|api`	`auto`	Auto prefers jina-v5-nano.
`--model`	str	provider-dependent	Provider-specific model, including aliases like `@tiny`, `@best`, `@multilingual-best`.
`--dimensions`	int	(none)	Matryoshka truncation (shorter vectors).

`kt search`

Search a session's memory. <session> accepts the same forms as kt embedding (legacy .kt also recognized).

kt search <session> <query> [flags]

Flag	Type	Default	Description
`--mode`	`fts\|semantic\|hybrid\|auto`	`auto`	Search mode. Auto picks semantic when vectors exist, else FTS.
`--agent`	str	(none)	Restrict to events from one agent.
`-k`	int	`10`	Max results.

Drive records

kt drive administers Drive records in a saved session non-interactively — it resumes the session through Studio (which resolves that node's Drive settings), runs one operation, prints a stable table or --json, and shuts down.

kt drive --session <id> [--json] {list | show | create | assign | transition | deliveries | replay}

--session <id> (required): session name/prefix or .kohakutr path.
--json: emit the service DTO shape instead of a table.

Subcommand	Form	Notes
`list`	`list [--status active,blocked] [--kind K] [--mine]`	Redacted rows.
`show`	`show <drive_id>`	Full record (use it to read the current revision).
`create`	`create --kind K --title T [--scope graph\|creature] [--priority N] [--spec-json JSON]`	Operator-owned Drive.
`assign`	`assign <drive_id> <creature> --revision N`	Assign to a graph member.
`transition`	`transition <drive_id> <status> --revision N [--reason R]`	Pause/resume/cancel/…
`deliveries`	`deliveries <drive_id>`	Delivery history.
`replay`	`replay <delivery_id>`	Replay a dead-letter delivery.

Mutations (assign, transition) require --revision N; omitting it fails with a refetch instruction rather than silently overwriting. Exit codes are meaningful for scripting (see Exit codes). Terminal propose/approve, unassign, and owner transfer are exposed through the HTTP API and the interactive /drives command rather than this top-level automation CLI.

Web and desktop UI

`kt web`

Run the web server (blocking, single process).

kt web [flags]

Flag	Type	Default	Description
`--host`	str	`127.0.0.1`	Bind host.
`--port`	int	`8001`	Bind port. Auto-increments if busy.
`--dev`	flag	(none)	API-only (serve frontend separately via `vite dev`).
`--log-level`	as `kt run`

`kt app`

Run the native desktop build (requires pywebview).

kt app [--port 8001] [--log-level ...]

`kt serve`

Daemon management for the web server. Process state lives under ~/.kohakuterrarium/run/web.{pid,json,log}.

`kt serve start`

Start a detached server process.

kt serve start [--host 127.0.0.1] [--port 8001] [--dev] [--log-level INFO]

`kt serve stop`

Send SIGTERM, then SIGKILL after the grace period.

kt serve stop [--timeout 5.0]

Flag	Type	Default	Description
`--timeout`	float	`5.0`	Seconds to wait for graceful shutdown.

`kt serve restart`

stop then start, forwarding all flags to start.

`kt serve status`

Print running / stopped / stale, PID, URL, started_at, version, git commit.

`kt serve logs`

Read ~/.kohakuterrarium/run/web.log.

kt serve logs [--follow] [--lines 80]

Flag	Type	Default	Description
`--follow`	flag	(none)	Tail the log.
`--lines`	int	`80`	Initial lines to print.

Extensions

`kt extension list`

List every tool, plugin, and LLM preset contributed by installed packages. Marks editable installs.

`kt extension info`

Show package metadata plus its creatures, terrariums, tools, plugins, and LLM presets.

kt extension info <name>

MCP (per-agent)

`kt mcp list`

List MCP servers declared in an agent's config.yaml mcp_servers: section. Columns: name, transport, command, URL, args, env keys.

kt mcp list --agent <path>

MCP servers can also live in the global catalog at ~/.kohakuterrarium/mcp_servers.yaml, managed by kt config mcp. The two registries are independent: per-agent entries are attached on agent start; catalog entries are not auto-attached but can be referenced by name.

File paths

Path	Purpose
`~/.kohakuterrarium/`	Home.
`~/.kohakuterrarium/llm_profiles.yaml`	LLM presets and providers.
`~/.kohakuterrarium/api_keys.yaml`	Stored API keys.
`~/.kohakuterrarium/mcp_servers.yaml`	Global MCP server catalog.
`~/.kohakuterrarium/ui_prefs.json`	UI preferences.
`~/.kohakuterrarium/codex-auth.json`	Codex OAuth tokens.
`~/.kohakuterrarium/sessions/*.kohakutr`	Saved sessions (legacy `*.kt` also accepted).
`~/.kohakuterrarium/packages/`	Installed packages (copies or `.link` pointers).
`~/.kohakuterrarium/run/web.{pid,json,log}`	Web daemon state.

Environment variables

Var	Purpose
`EDITOR`, `VISUAL`	Editor for `kt edit` / `kt config edit`.
`VIRTUAL_ENV`	Reported by `kt --version --verbose`.
`<PROVIDER>_API_KEY`	Whatever `api_key_env` each provider references.
`KT_<SHELL>_PATH`	Override a specific shell executable (for example, `KT_BASH_PATH`); takes precedence over `KT_SHELL_PATH`.
`KT_SHELL_PATH`	Generic shell executable override used by the `bash` tool when no per-shell override is set.
`KT_SESSION_DIR`	Override session directory for the web API (default `~/.kohakuterrarium/sessions`).

Exit codes

0: success.
1: generic error.
Editor exit code, for kt edit / kt config edit.
kt drive uses an extended set so scripts can branch: 0 ok, 1 error, 2 usage, 3 conflict (revision moved — refetch), 4 not found, 5 permission denied.

Interactive prompts

These commands may drop into interactive prompts:

kt resume with no argument, or ambiguous prefix.
kt terrarium run when there is no root and no --seed.
kt login.
Every ... add subcommand under kt config.
kt config key set with no value.

Package reference syntax

@<pkg-name>/<path-inside-pkg> resolves to ~/.kohakuterrarium/packages/<pkg-name>/<path-inside-pkg>, or follows <pkg-name>.link. Accepted by kt run, kt terrarium run, kt edit, kt update, and kt info.

Terrarium TUI slash commands

Inside kt terrarium run --mode tui, the input bar accepts slash commands. Built-ins: /exit, /quit. Additional commands come from the terrarium's registered user commands. See builtins.md#user-commands.