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.
Install
Section titled “Install”curl -fsSL https://kora-ai.download/release/cli/install.sh | shBuilds for Apple Silicon Macs and Linux (x64/arm64). From a source checkout instead: go build -o bin/kora ./cmd/kora.
Profiles
Section titled “Profiles”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.
Commands
Section titled “Commands”| 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.
Settings area in the TUI
Section titled “Settings area in the TUI”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).aadds,eedits,rrefreshes,enteropens its models,xremoves — 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.
xkills the selected host (tmux session, wirekill, subagent abort, or stale-record cleanup);rrefreshes. - Agent surfaces — while a session has background subagents, the footer shows
↓ N subagents; pressing↓on an empty composer lists the agents (main first) andenterswitches to that agent’s live surface. Rows and headers showstatus · elapsed · tokens(provider-reported usage);escsteps back.
Exit codes
Section titled “Exit codes”| 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 |
Output channels
Section titled “Output channels”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.
Troubleshooting
Section titled “Troubleshooting”kora: unknown flag "--json"→ you’re running an older installed binary; rebuild or install the current one.no serve on this profile→ startkora servefirst, and check you passed--dev(or not) consistently.- Session runs the wrong provider → provider/model are session attributes; change them in
kora chatwith/providerand/model.attachcannot switch them. - A killed process left the session locked → locks are advisory and reclaimed automatically when the recorded PID is dead.