CANBAN // DOCS // CLI
Canban CLI, Agent Optimization & --human
The canban binary (crates/cli/src/main.rs) talks to the exact same AppServer JSON-RPC authority as the native desktop UI. Its response contract is Agent-first by default to minimize context tokens, while --human makes the same commands comfortable to read and script interactively.
Core CLI commands
Global options --home <PATH> (CANBAN_HOME), --endpoint <PATH> (CANBAN_ENDPOINT), --human, --fields <COLS>, and --full work across subcommands:
| Command | Purpose |
|---|---|
canban snapshot, canban status | Fetch full app.snapshot state or herdr.status runtime health. |
canban call <METHOD> '<JSON>' | Invoke any public AppServer JSON-RPC method (pass @/path/to/params.json for file payloads). |
canban card show, card update, card adopt | Inspect the Card, update --title / --file, or adopt --stage develop onto the live PTY without spawning a duplicate Agent. |
canban report | Report execution outcome (--state: completed, backlog, blocked, failed, working; --message, --file) for a Card or --schedule-run-id. |
canban reply | Answer a follow-up question (--to <QUESTION_ID> --file <PATH>) without ending the active task. |
canban bind-session | Bind provider --session-id <ID> onto the active Card, schedule run, merge batch, or configuration session. |
canban review draft, review clear | Stage or discard local unpublished diff review JSON ({ summary, verdict, comments }) for the Card Diff UI. |
canban workflow sources, export, submit, set-default | Manage SQLite-backed workflow_sources (--project-id or --global, --check dry-run, and global defaults). |
canban schedule | list, runs, create, trigger, toggle (--on / --off), delete, and artifact for Global or Project cron workflows. |
canban worktree gc | Clean up merged clean worktrees (--merged-before 7d, --dry-run, --env-dirty, --fail-on-dirty). |
canban batch report | Report _merge_queue @merger resolution (--state, --evict <CARD_NUMBER>). |
canban serve, pair, service | Run headless AppServer (--tailscale, --port 7680, --listen), print canban:// pairing URIs, or manage systemd / launchd services. |
canban skill, --skill, build-info | Print bundled SKILL.md or immutable release build metadata without opening application data. |
Agent-first optimizations
Canban designs its CLI and RPC layer (crates/app-server/src/representation.rs) specifically to prevent wasted tokens, stale writes, and fragile lifecycle heuristics:
- Compact single-line JSON default: Every query and mutation prints a single compact JSON line to stdout regardless of whether stdout is a terminal, and emits structured
{"error":{"message":...}}on stderr with a non-zero exit code. - Server-side response shaping (
--fieldsvs.--full):card.show,card.get, andcard.listdefault to slim summaries (id,number,title,stage,revision), and writes return smallacceptedreceipts without echoing Card bodies. Pass--fields number,title,body,stage,revisionto project exact top-levelCARD_FIELDS/EVENT_FIELDSon the server, or--full(view: "full") for the complete business view. Invalid field names fail pre-dispatch validation before any mutation runs. - Bounded keyset pagination:
card.list(limit1..500, default 50) uses an opaquecursorwithcursor_stale/cursor_scope_mismatchguards;timeline.listfilterskindsin SQL, normalizes comment text once intobody, and exposesnext_cursor,last_sequence, andhighwater. - Zero-config environment injection: Launched sessions automatically receive
CANBAN_CLI,CANBAN_ENDPOINT,CANBAN_HOME,CANBAN_CARD,CARD_ID,CANBAN_PROJECT,CANBAN_PROFILE_ID, andCANBAN_RUN_DIR(plusCANBAN_SCHEDULE_RUN_ID,CANBAN_SCHEDULE_ID, andCANBAN_BATCH_IDwhen applicable), and inferproject_idfrom the worktree CWD when omitted. request_keyidempotency & updater handoff: Mutating CLI commands attach arequest_key(or accept--request-keyfor safe retries, unaffected by--fields/--full). During live daemon restarts,report,batch report, andreplyqueue viacanban_updater::handoffand emit{"queued":true,"request_key":...}.- Explicit
report --stategates: Terminal exit or idle never advances workflow steps; agents advance only by declaringcompleted,blocked,failed,backlog, orworking. - Bundled
canban skill(SKILL.md):canban skill/canban --skillprints the binary-lockedskills/canban/SKILL.mdinstructions directly, whileAppServer::openmaterializes<CANBAN_HOME>/skills/canban/SKILL.md. - Local unpublished
review draft:canban review draft --file "$CANBAN_RUN_DIR/review_draft.json"stores inline review findings locally in SQLite so humans inspect and publish from the Diff UI rather than letting agents post directly to GitHub.
Human usage (--human)
Humans can inspect, debug, and script the exact same CLI comfortably using the global --human flag. As verified in crates/cli/src/main.rs (Output::encode), --human only pretty-prints (serde_json::to_string_pretty) the response—it never triggers extra RPC fields or alters server-side selection:
# Pretty-print the full Board snapshot for inspection
canban --human snapshot
# Pretty-print only the selected Card fields (no wasted payload)
canban --human --fields number,title,stage card show
# Call any JSON-RPC method interactively with readable formatting
canban --human call project.list '{}'
# Combine with --card / --full or pipe compact JSON into jq
canban --human --full card show --card 42
canban call card.list '{"stage":"develop","limit":20}' | jq '.items[] | [.number, .title]'Tip: Use --home <PATH> or --endpoint <PATH> alongside --human when inspecting an isolated development instance or remote socket.
Bundled Canban Skill (canban skill)
Canban embeds a version-locked Agent Skill (skills/canban/SKILL.md, compiled into canban_context::SKILL_MD in crates/context/src/lib.rs) so any coding agent learns the exact CLI contract without Canban silently mutating user-global agent folders:
- Zero-side-effect inspection & home materialization: Running
canban skillorcanban --skill(crates/cli/src/main.rs) prints the compiledSKILL.mddirectly to stdout without opening SQLite or sockets. WhenAppServer::openstarts (orstage_remotesyncs a remote host), it atomically materializes<CANBAN_HOME>/skills/canban/SKILL.mdviamaterialize_skillwhenever bytes differ—keeping user-global agent directories untouched. - Install or refresh into your agent: In desktop Agent Setup and Settings → Agents & Identities (
crates/ui/src/agents_setup.rs), Canban surfaces thenpx skills addcommand for your active home, or you can writecanban skilldirectly into any agent'scanban/SKILL.mddirectory:
# Install or refresh from the materialized Canban home directory
npx skills add ~/.canban/skills --skill canban -g
# Or print and write the exact binary-locked skill file directly
canban skill > ~/.agents/skills/canban/SKILL.md- What the Skill teaches Agents: Session preflight (
CANBAN_CLIandCANBAN_ENDPOINTchecks), keeping payloads in$CANBAN_RUN_DIRoutside Git, slimcard showandcard adopt, explicitreport --statecompletion gates,reply --tofor live follow-ups, local unpublishedreview draft,workflow submit --check, andworktree gc.