# 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 (`--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`.
