CLI reference

Every command, option, limit and exit code of kabu 2.5.1, as the CLI’s contract defines them. Scripts and agents may rely on all of it: options are only ever added, and changing or removing one is a breaking change. For a walkthrough, start with the kabu CLI.

Commands

kabu --help lists the commands, exit codes and environment. kabu COMMAND --help (or kabu help COMMAND) lists every option with its limit, and examples. kabu --version prints kabu X.Y.Z. kabu alone is a usage error (exit 2). kabu login with neither flag asks for the key only when stdin is a terminal; --api-key - reads it from stdin. A key is never shown in an error. login --device prints on stderr, first, In the Kabu app, open Connect a computer and enter the code: WXYZ-1234, then a line with the link that approves the same code in a browser, and a line saying that an admin or owner of the workspace approves it.

Text

One argument is the message; two are TITLE MESSAGE. --title (or --ask, --ask-text) and --message set them by flag. Without a title, the title is the message’s first line, cut to 120 characters; without a message, the message is the title. - as the message, --code, --diff or --quote reads stdin as UTF-8 (invalid bytes become U+FFFD), for one of them at most. The title takes 120 characters and the message 8192, counted as the API counts (code points). Longer text is refused, never cut. The request goes as UTF-8 JSON, and one over the API’s 64 KiB (65,536 bytes) is refused before any call.

Options of send and ask

Asks only (anywhere else they are refused):

Every option is validated before any HTTP call: limits, enums, ids, mutually exclusive and dependent flags, files that exist. The request body is the contract’s MessageCreate; the CLI sends body, never its alias message.

Exit codes

Output

stdout carries one JSON object and nothing else.

• send: {"ok": true, "id": "msg_…", "status": "sent", "attachments": N, "project": "…", "project_source": {…}, "session": null}.

• ask, keys sorted: {"choices", "decision", "id", "option", "outcome", "status", "text", "values", "via"}, whatever the exit code. outcome is answered, expired or cancelled; decision is the API’s, as given (the legacy deny reads reject), or null; option is the chosen option’s id and text a typed answer. Expired and cancelled asks print {"decision", "id", "outcome", "status"}. The exit code says what to do, and only an explicit approve or the answer to a choice, multi or text ask is 0:

  The answer	decision	Exit
  Approved	approve	0
  A choice, multi or text ask answered: option, choices, text or values	respond	0, whatever was chosen: branch on option
  Rejected	reject (or deny)	10
  A confirm answered with a typed reply (--allow-reply): read text	respond	10
  Expired; cancelled	as given, or null	20; 21
  Anything else (edit, ignore, a decision kabu does not know, or none)	as given, or null	3

• Every send and ask, --no-wait and the answer included, also prints project, the one sent (null when no rule named one), project_source (Project resolution) and session, the message’s session as the API has it (null for none).

• status, session: the API’s object as returned.

• An ask kabu stops waiting for is still open: the error adds its id, and the hint is kabu status ID --wait 50, never to ask again.

• An ask the API no longer has while kabu waits for it (a 404: it was deleted, as when its project is) can never be answered: kabu stops at once, with no retry, and exits 21 with {"error": {"code": "ask_gone", "message", "hint", "status": 404, "id"}}, whose hint is to ask again only if the answer is still needed.

• When the API answers session: null for the session kabu named, that session no longer exists (it was deleted with its project) and the message went without one: the output adds session_gone, its id, and kabu never names it again (Session, under Configuration).

• kabu status on a message the API does not have (404) keeps the API’s error, exit 3, with a hint that it was deleted (as when its project is) or never existed, so it will never be answered. kabu session update or end with a session the API reported gone exits 3 with session_gone and makes no call; a 404 from either gets the same hint as status.

An error is one JSON line on stderr: {"error": {"code": "…", "message": "…", "hint": "…"}}. The message names the flag and the allowed values or limit; the hint is the next step, usually a corrected command. API errors add status (HTTP), and param and request_id when the API gives them; their code is the API’s problem code, or network_error. Nothing is ever coloured.

MCP bridge

kabu mcp serves the API’s MCP tools (/mcp, streamable HTTP) to a harness that starts it as a stdio server, such as claude mcp add kabu -- kabu mcp or the Kabu plugin’s .mcp.json. It finds the key and base URL as every command does (Configuration, below), so the harness’s config holds no key.

• Each line on stdin is one JSON-RPC message, POSTed to {base URL}/mcp with the key as a bearer token, unchanged but for one addition: a tools/call with no project argument, of a tool whose input schema in the server’s tools/list has a project property, gets the project kabu resolves for that call (Project resolution) when rule 1 to 5 names one, never a <folder>@<host> name, and only when the key is bound to no project: kabu mcp asks GET /v2 once, when it starts, and adds nothing if the key has a project or the answer does not come. Requests run side by side, so a waiting ask never holds up another call; notifications and replies keep their order.
• Presence (ADR 021, 022). Nothing before its first tools/call. Then, when a harness started it (its parent is one, as for an MCP server; never a kabu mcp that a script in an agent session runs) and presence is on, kabu mcp gets or creates that harness’s automatic session once, on the hooks’ HMAC ladder (Presence: the same external_id, so one ses_ per run, shared with the hooks and kabu send), adds it as session to the calls of the tools that take a project, unless a call names one, writes an online record from source mcp and starts kabu presence run when none runs. The hooks’ working and idle beat that online. At EOF (or SIGTERM) it writes an offline record, which the reporter sends within 5 s; it never ends the session.
• Each reply is printed on stdout as one line: the JSON body, or each event of a text/event-stream body as it arrives, so the harness sees a long wait’s progress notifications before its answer. An empty reply, such as a notification’s 202, prints nothing.
• The Mcp-Session-Id the server issues is sent on every later request, and replaced when the server sends a new one.
• Nothing is retried, so a tool call is never sent twice. A request with no answer from the API (a network error, an HTTP error status, a redirect, a body that is not JSON, or an empty body or event stream with no reply for its id) gets a JSON-RPC error with its id: {"code": -32000, "message": "…", "data": {"code", "status"}}, where message ends with the hint. The same error is logged on stderr as one JSON line. An id is answered once: when the API’s answer came before the failure, such as a stream that breaks after its reply, the failure is only logged.
• stdout carries only JSON-RPC; anything else goes to stderr. Exit 0 once stdin closes and the requests in flight are answered, 2 with no key (missing_api_key) or a bad option, before reading stdin, and 130 when interrupted.

Reliability

• One Idempotency-Key (a uuid4) per invocation on POST /v2/messages, the same on every retry, so a message is never sent twice. Uploads and session calls use keys derived from it.
• Up to 3 retries, on network errors, 5xx, 429 with Retry-After and 409 idempotency_key_in_use. Each waits Retry-After (up to 30 s; a longer one fails at once) or 0.5, 1 and 2 s. Any other 4xx fails at once.
• Each response may take --timeout seconds (default 30), plus the wait the API was asked to hold for.
• While an ask is pending, network errors, 5xx and 429 only delay the wait: kabu polls again every 5 s, up to expires_in + 120 s. Any other refusal, or that deadline, ends the wait with exit 3 and the ask’s id, but for a 404, which ends it with ask_gone, exit 21 (Output).
• A redirect is never followed, so the key never goes to another URL: a 3xx is an API error, exit 3 with its status (in kabu mcp, a JSON-RPC error). Set KABU_BASE_URL to the final URL instead.

Configuration

Presence

Whether an agent is live (ADR 021, docs/adr/021-agent-presence.md): working, idle, waiting at the computer or gone. kabu --help names these commands in a paragraph of their own, after Commands.

• What leaves the machine: state enums (runtime, attention, source), ids made by HMAC with the installation secret (the session’s external_id, the ln_ lane), the harness’s name as the session’s agent (claude-code) and the project the session runs in, as kabu send sends it. Never a prompt, path, tool name, host name, the client’s title or its raw session id; the session’s title is the constant <harness> session.
• The hook. PRESENCE_HOOK, written out as the plugin’s hooks/presence.sh and by kabu presence install as ~/.kabu/presence-hook.sh (~/.kabu is KABU_HOME when set), mode 0600. A harness runs it as kabu_event=EVENT; (. FILE) || true: a subshell of the hook’s own shell sources it, so it starts no program (but kabu presence run, below), never reads its input (a harness may hold it open), has no unbounded loop, never calls the network and always exits 0. Events, in Claude Code’s names or Copilot CLI’s: SessionStart (sessionStart) idle, UserPromptSubmit (userPromptSubmitted), PreToolUse (preToolUse) and PostToolUse (postToolUse) working, Notification (notification) attention terminal until the next event (Claude Code’s matcher passes only the types that need the user: permission_prompt, elicitation_dialog, elicitation_url_dialog, worker_permission_prompt, agent_needs_input), Stop (agentStop) idle, SessionEnd (sessionEnd) offline. kabu mcp writes records too, with source: mcp and runtime online, then offline (MCP bridge); a lane’s state is its hooks’ latest record when it has one, else kabu mcp’s.
• Records. Each event is a new file, l<harness pid>-<seq>.json (0600), created no-clobber at the next free seq, in this user’s machine-local folder kabu-presence-$USER (0700) of KABU_RUNTIME_DIR, else XDG_RUNTIME_DIR, else TMPDIR, else /tmp (on a Mac also the per-user temp folder): {v, event, runtime, attention, seq, pid, sid, pane}, where pid is the hook’s parent (the harness), sid Claude Code’s CLAUDE_CODE_SESSION_ID when that Claude is the parent, and pane HERDR_PANE_ID. A folder that is a link or not this user’s is never used; no record is written through a link or over another file, so concurrent hooks lose no event and the state is the highest seq’s. The hook starts kabu presence run at SessionStart, and at a turn’s other events when none runs (run.pid there).
• kabu presence run, one per machine: an exclusive lock on run.lock in that folder, which is machine-local, so machines that share a home each run theirs. Every 2 s it folds each harness’s records (keeping only the latest) and checks its process: one that exited reads offline at once, and one that is a zombie or whose id another process took within 10 s. A record older than its harness’s process (another process had that id) is never adopted. It sends PUT /v2/presence with every live agent session (at most 20; the API takes one left out offline), once a minute or next_beat_in, and at once on a change, but working and idle wait 5 s to settle, never more than 10 a minute. A turn with no event for 15 minutes and no tool running reads idle. Each agent session’s Kabu session is got or created once, automatic (automatic: true: idle, no Live Activity of its own, ADR 022): external_id kp_ and HMAC(installation secret, harness ‖ session id, else its process id and start time), agent the harness, title <harness> session, project the one the harness’s folder names (never a temp folder’s or <folder>@<host>); it is kept beside the records, per API and key. The reporter is instance (pin_…) and generation, raised at every start, with the secret in ~/.kabu/presence/reporter-<machine>.json (0600; one per machine: KABU_MACHINE_ID, else Linux’s machine-id, the Mac’s hardware UUID or the host name, hashed). A stale batch resumes above the API’s generation; a session the API reports ended or gone is replaced by a new one. It exits after 10 minutes with no agent session, once presence is off (its sessions sent offline first), or when its folder or KABU_HOME is gone. Every file it writes is new (0600) and renamed into place; it opens none through a link.
• kabu send and ask join it. In an agent session whose records exist and are newer than its harness’s process (the harness is kabu’s nearest harness ancestor), with no --session or KABU_SESSION, a message goes in that agent session’s Kabu session, found or created as above, in one try of up to 3 s; KABU_AUTO_SESSION applies only without one. If the API answers session_ended, the message is sent again without it.
• kabu presence install writes the hook and adds it for the seven events to Claude Code’s settings (CLAUDE_CONFIG_DIR, else ~/.claude, settings.json: a group per event, matcher the types above for Notification) or Copilot CLI’s (COPILOT_HOME, else ~/.copilot: its native keys sessionStart, userPromptSubmitted, preToolUse, postToolUse, notification, agentStop, sessionEnd, each a flat {type, bash, timeoutSec}), or --settings. Entries that run presence-hook.sh are replaced, others kept; running it again changes nothing. Each change first saves a backup under a name no other has (settings.json.bak-kabu-presence-<time>-<ns>-<id>, 0600), and the file is written at once, never looser than 0600; a file that is not JSON is left alone (exit 2, invalid_settings). uninstall puts back the exact bytes from before the install when the file is as kabu left it (or removes the file kabu made), else takes out only kabu’s entries; the hook file goes once no settings use it (~/.kabu/presence/installs.json keeps what was installed where). The Kabu plugin needs neither.

Agent resolution

--agent, then KABU_AGENT (or AGENT_NOTIFIER_AGENT), then the agent saved by kabu login --agent, then the harness that runs kabu:

1. The nearest ancestor process named claude, copilot, codex, cursor-agent, gemini, opencode, aider, goose, amp or pi. Process names only: never their arguments, which can hold secrets. kabu reads its ancestors from /proc on Linux and with one ps call elsewhere; a ps that cannot show start times still gives their names.
2. AI_AGENT, as a slug.
3. Markers harnesses set for the commands they run: CLAUDECODE or CLAUDE_CODE_ENTRYPOINT (claude-code), CURSOR_AGENT or CURSOR_TRACE_ID (cursor), GEMINI_CLI (gemini-cli), CODEX_THREAD_ID or CODEX_SANDBOX (codex), PI_CODING_AGENT (pi).
4. Otherwise kabu-cli.

Project resolution

Without --project, kabu sends the project of the first rule below that names one. Every send, ask, dry run and kabu whoami says which in project_source: {"rule"}, plus, where they apply, the harness process, the dir the rule read, via (dotenv or git), the environment variable (only with session_root), and cached: true when the project was read back from the agent session’s cache. With --project it is {"rule": "flag"}.

• Agent session. The nearest ancestor process named as a harness (Agent resolution, step 1), such as claude or copilot. Its root is CLAUDE_PROJECT_DIR when set (Claude Code sets it for hooks and MCP servers, Copilot CLI for plugin hooks), else the harness process’s working folder: the one it started in, or the one the user moved the session to (Copilot CLI’s /cd). So cd in a command, which moves only that command’s shell, never changes the project. With no harness among kabu’s ancestors, rule 3 does not apply, and rule 2 only with CLAUDE_PROJECT_DIR.
• What a folder names. KABU_PROJECT (else AGENT_NOTIFIER_PROJECT) in .env.local, checked first, or .env, from the folder up to its git repository’s top, then in the main worktree’s root, as .env is usually untracked and so absent from linked worktrees; files outside the repository are never read (via: dotenv). Otherwise the git repository’s name: the origin remote’s, else the main worktree’s folder name, the same from any nested folder or linked worktree (via: git). Otherwise nothing. A folder that no longer exists names nothing.
• Temp folders. A folder in /tmp, /var/tmp, /var/folders or $TMPDIR, symlinks resolved (so /private/tmp too), names nothing, but for a worktree of a repository whose main worktree is outside them, which names that repository’s project. cd /tmp/x && kabu send … keeps the session’s project, else the saved one, else none.
• No <folder> of rule 6 is a temp folder, /, your home folder or a folder that no longer exists.
• Kept per agent session. Rules 2 and 3 keep what they named in the cache’s sessions/ (Configuration), one file per harness process, named by its process id and start time, with the session root it was named under. A later process that reuses the id never finds another session’s project, so a file is only read while its process runs, and only while the session’s root is the folder it was kept under; when the root moves, the session resolves again. A project is kept as a name, never a project id: a project deleted in Kabu is created again by the next message that names it. Files unused for 7 days are removed. Where a harness’s start time cannot be read, nothing is kept.
• kabu mcp resolves the project for each tool call, as kabu send would (MCP bridge).

Calls with no command (kabu.py compatibility)

A call whose first word is not a command is send, or ask when --ask or --ask-text is given, so ~/bin/kabu.py can become a one-line shim:

Only a yes or no pair makes a confirm: yes then no, y then n, or approve then reject, in any case, with no --type and no --allow-free-form. Its first choice exits 0 and its second 10, as kabu.py’s 0 and 1. Any other choices, and any with --allow-free-form, are a choice, which exits 0 and names what was picked in option (or the typed answer in text). The rest is kabu’s, not kabu.py’s: an ask exits 0, 3, 10, 20 or 21 (kabu.py exited with the chosen index, 1 on reject and 124 on timeout), -p is --project (kabu.py: priority), and an unknown flag is refused rather than ignored, with kabu’s way when it has one (--quiet, --id-only, --fyi, --category, --metadata, --max-retries, --client-event-id, --check-status).

A first word is never sent as a message when it is one of kabu.py’s other commands, daemon, listen, service, steer, identity or project: steering and project settings are not in kabu, so it exits 2. Neither is a word that looks like a mistyped command, such as kabu sned "hi", which is refused with a suggestion. Send such a word with kabu send.