Skip to Content
Krad ADE
Agents API

krad CLI

Every command of the krad CLI, the request it makes, its options, its JSON output and its exit codes.

krad and krad-ade-agents are the same program. The app puts both on the PATH of its terminals, and the help names the one you typed. Inside the app's terminals it finds the API through the KRAD_ADE_* variables; elsewhere through api.json.

Usage
krad <command> [args] [--json]
  • --json on any command prints the response line instead of text. For status it prints an object with working, waiting_for_input, done, idle and exited lists.
  • --version prints the build.
  • krad help prints the guide, its commands and the exit codes; krad help lead prints the guide a lead follows.

Agents

CommandRequest
krad list [--all]List, or ListAll
krad agents list [--all]The same
krad agents watch [--group G] [--harness H] [--terminal ID]... [--since SEQ --stream ID]SubscribeAgents. Prints the snapshot, whose first line names its seq and stream, then one line per event until interrupted. --harness takes claude, codex, opencode, acp:<id> or a display name.
krad statusList, grouped by state; agents of unknown harness are left out

Messages and Workers

CommandRequest
krad send <id> <message>Send
krad check [--wait SECS]Check
krad wait <id> [--timeout SECS]Wait; 600 seconds by default, at most 1800
krad read <id> [--lines N]Read; 40 lines by default
krad spawn --agent <claude|codex|opencode|acp-id> [--worktree NAME] <task>Spawn
krad close <id> [--force] [--remove-worktree]Close an agent; --force is cancel_turn, --remove-worktree is remove
krad close --session <id> [--force] [--remove-worktree]Close a session
krad close --all-idle [--remove-worktree]Close every finished Worker

send, spawn and close direct Workers, so only a lead may run them. See Lead and Workers.

Sessions, worktrees, files and changes

CommandRequest
krad sessionsSessions
krad session create [NAME] [--group GROUP]CreateSession
krad session close <id>CloseSession
krad worktree create <name>CreateWorktree
krad open <file>[:LINE[:COLUMN]]OpenFile
krad changes [<session id>]Changes, as a list of files
krad diff [<session id>]Changes, as the patch

Kraddies and automations

CommandRequest
krad kraddie listKraddies
krad kraddie run <name> [prompt]RunKraddie
krad kraddie remember <name> <text>RememberKraddie
krad kraddie memory <name>KraddieMemory
krad kraddie memory list|show <name>KraddieRecall
krad kraddie chat new <name>NewKraddieChat
krad kraddie share|unshare <reader> <read-from>ShareKraddieMemory
krad automation listAutomations
krad automation run <name> [prompt]RunAutomation
krad automation enable|disable <name>SwitchAutomation

krad pet still runs krad kraddie, from the feature's former name; it is not listed in the help. See Kraddies and Automations.

Variants

CommandRequest
krad variants run --variant <agent> [--model M] [--instruction TEXT] ... [--test TASK] [--group G] <task>RunVariants; two to four --variant, each followed by its own --model and --instruction
krad variants status [<run id>]Variants
krad variants pick <run id> <variant> [--apply] --yesPickVariant; refused without --yes
Two variants with a test
krad variants run \
  --variant codex --model gpt-5.5 \
  --variant claude --instruction "Keep the diff small" \
  --test "cargo test" \
  "Fix the flaky upload test"

See Variants.

Code and tools

CommandRequest
krad code <diagnostics|definition|references|hover|rename> FILE[:LINE:COLUMN] [NEW_NAME]Code: asks the language servers
krad tools, krad tool <name> [JSON arguments]Tools, ExtensionTool

The API itself

CommandRequest
krad apiHello: the API version the app serves
krad api info [--show-token]Hello and the staleness check
krad help [lead]The guide

Commands for the harnesses

The verbs hook, ask, statusline and mcp are run by the harnesses the app configures, not by people, and are not listed in the help. krad mcp serves the code tools and the memory tools as a stdio MCP server named krad-code.

Exit codes

ExitMeaning
0Done
1Wrong arguments
2The app cannot be reached
3Timed out
4No such agent, session or file
5Refused for this caller
6The app speaks another API version
7The app could not do it

The mapping from each error code is in Errors and exit codes.

On this page