Skip to content

Kora CLI

Kora CLI is the terminal twin of Kora Desktop: same session files, same providers, same workspace. Sessions started in one surface can be continued in the other.

Terminal window
curl -fsSL https://kora-ai.download/release/cli/install.sh | sh

Builds for Apple Silicon Macs and Linux (x64/arm64). From a source checkout instead: go build -o bin/kora ./cmd/kora.

The profile is the directory that holds sessions, keys and settings.

Selector Result
(default) ~/.kora — shared with release builds of Kora Desktop
kora --dev <cmd> ~/.kora-dev — development profile
KORA_PROFILE Named profile override
KORA_PROFILE_ROOT Explicit directory override

Precedence: KORA_PROFILE > KORA_PROFILE_ROOT > --dev > default. Use --dev consistently across a command sequence — serve, attach and mcp-control all resolve the profile’s socket from it.

Command Does
kora TUI on the latest session; bare PROMPT... runs one headless turn
kora new Create a session, print its id
kora chat [id] TUI on a session; --tmux wraps it (see tmux)
kora -r [name|id] Resume a session by name or id
kora send <id> [-y] [--json] <PROMPT...> One-shot headless turn (see Headless JSON)
kora sessions [--json] List sessions; ● live marks live ones
kora inspect <id> Print the session envelope as JSON
kora key [set|<api-key>|clear] Manage the Kora API key
kora serve [-y] Control plane on <profile>/serve.sock (see serve & attach)
kora attach <id> Attach a terminal to a serve-hosted session
kora mcp Apple Foundation Models tools over MCP stdio
kora mcp-control Session control tools over MCP stdio (see MCP control)
kora --version Print the version

Global flags: --dev, --no-splash. -y/--yes auto-approves tool calls on send, chat, serve.

The fullscreen overlay (/settings or /help) is the settings area: searchable tabs for commands, keys, display, permissions and the live settings state, plus two interactive tabs.

  • Providers — index of every selectable provider (custom first, builtin after, ✓ on the session’s active one). a adds, e edits, r refreshes, enter opens its models, x removes — all through the same flows as /provider <cmd>, which stays the quick-set command.
  • Live — every live kora host on the profile: tmux-wrapped chats, serve attachments and in-process subagents. x kills the selected host (tmux session, wire kill, subagent abort, or stale-record cleanup); r refreshes.
  • Agent surfaces — while a session has background subagents, the footer shows ↓ N subagents; pressing ↓ on an empty composer lists the agents (main first) and enter switches to that agent’s live surface. Rows and headers show status · elapsed · tokens (provider-reported usage); esc steps back.
Code Meaning
0 Success / clean detach
1 Turn or runtime error
2 Usage error — also “no serve on this profile” from attach
3 attach: session writer slot already held
4 attach: serve closed the connection mid-attach

stdout carries answers and JSON frames; chrome (banner, tool lines, notes, errors) goes to stderr. In the JSONL modes every line on stdout is a protocol frame — safe to pipe into jq.

  • kora: unknown flag "--json" → you’re running an older installed binary; rebuild or install the current one.
  • no serve on this profile → start kora serve first, and check you passed --dev (or not) consistently.
  • Session runs the wrong provider → provider/model are session attributes; change them in kora chat with /provider and /model. attach cannot switch them.
  • A killed process left the session locked → locks are advisory and reclaimed automatically when the recorded PID is dead.