CANBAN

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:

CommandPurpose
canban snapshot, canban statusFetch 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 adoptInspect the Card, update --title / --file, or adopt --stage develop onto the live PTY without spawning a duplicate Agent.
canban reportReport execution outcome (--state: completed, backlog, blocked, failed, working; --message, --file) for a Card or --schedule-run-id.
canban replyAnswer a follow-up question (--to <QUESTION_ID> --file <PATH>) without ending the active task.
canban bind-sessionBind provider --session-id <ID> onto the active Card, schedule run, merge batch, or configuration session.
canban review draft, review clearStage or discard local unpublished diff review JSON ({ summary, verdict, comments }) for the Card Diff UI.
canban workflow sources, export, submit, set-defaultManage SQLite-backed workflow_sources (--project-id or --global, --check dry-run, and global defaults).
canban schedulelist, runs, create, trigger, toggle (--on / --off), delete, and artifact for Global or Project cron workflows.
canban worktree gcClean up merged clean worktrees (--merged-before 7d, --dry-run, --env-dirty, --fail-on-dirty).
canban batch reportReport _merge_queue @merger resolution (--state, --evict <CARD_NUMBER>).
canban serve, pair, serviceRun headless AppServer (--tailscale, --port 7680, --listen), print canban:// pairing URIs, or manage systemd / launchd services.
canban skill, --skill, build-infoPrint 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 (--fields vs. --full): card.show, card.get, and card.list default to slim summaries (id, number, title, stage, revision), and writes return small accepted receipts without echoing Card bodies. Pass --fields number,title,body,stage,revision to project exact top-level CARD_FIELDS / EVENT_FIELDS on 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 (limit 1..500, default 50) uses an opaque cursor with cursor_stale / cursor_scope_mismatch guards; timeline.list filters kinds in SQL, normalizes comment text once into body, and exposes next_cursor, last_sequence, and highwater.
  • Zero-config environment injection: Launched sessions automatically receive CANBAN_CLI, CANBAN_ENDPOINT, CANBAN_HOME, CANBAN_CARD, CARD_ID, CANBAN_PROJECT, CANBAN_PROFILE_ID, and CANBAN_RUN_DIR (plus CANBAN_SCHEDULE_RUN_ID, CANBAN_SCHEDULE_ID, and CANBAN_BATCH_ID when applicable), and infer project_id from the worktree CWD when omitted.
  • request_key idempotency & updater handoff: Mutating CLI commands attach a request_key (or accept --request-key for safe retries, unaffected by --fields / --full). During live daemon restarts, report, batch report, and reply queue via canban_updater::handoff and emit {"queued":true,"request_key":...}.
  • Explicit report --state gates: Terminal exit or idle never advances workflow steps; agents advance only by declaring completed, blocked, failed, backlog, or working.
  • Bundled canban skill (SKILL.md): canban skill / canban --skill prints the binary-locked skills/canban/SKILL.md instructions directly, while AppServer::open materializes <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:

sh
# 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 skill or canban --skill (crates/cli/src/main.rs) prints the compiled SKILL.md directly to stdout without opening SQLite or sockets. When AppServer::open starts (or stage_remote syncs a remote host), it atomically materializes <CANBAN_HOME>/skills/canban/SKILL.md via materialize_skill whenever 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 the npx skills add command for your active home, or you can write canban skill directly into any agent's canban/SKILL.md directory:
sh
# 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_CLI and CANBAN_ENDPOINT checks), keeping payloads in $CANBAN_RUN_DIR outside Git, slim card show and card adopt, explicit report --state completion gates, reply --to for live follow-ups, local unpublished review draft, workflow submit --check, and worktree gc.