honcho-cli

# Honcho CLI `honcho` wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation. Use it to inspect workspace state, debug peer memory, and diagnose the dialectic. ## Output & config - **TTY**: human-readable tables (default when interactive) - **Piped / `--json`**: JSON — collection commands emit arrays, single-resource commands emit objects - **Exit codes**: `0` success · `1` client error (bad input, not found) · `2` server error · `3` auth error - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars. ## Command groups - `honcho config` — CLI configuration - `honcho start` / `stop` / `status` — local Docker stack (does not change `environmentUrl`). First start pins the Honcho image digest and writes `config.toml` into the profile. Pass `--setup basic` or `--setup advanced` for an interactive config wizard (TTY only; writes `.env` overrides). `honcho status` lists every profile; pass `--profile` for one. - `honcho workspace` — inspect, delete, search, chat - `honcho peer` — inspect, card, chat, search - `honcho session` — inspect, view (transcript), context, summaries - `honcho scope` — list, create, inspect, sessions, add-sessions, remove-session, status - `honcho message` — list and get - `honcho conclusion` — list, search, create, delete ## Rules - Always pass `--json` when processing output programmatically. - Run `honcho peer inspect` before `honcho peer chat` to understand context. - Use `honcho session context` to see exactly what an agent receives. - Never run `honcho workspace delete` without `honcho workspace inspect` first. - Compare peer card with conclusions to understand memory state. - After `honcho scope add-sessions`, check `honcho scope status <name>` before a scoped `chat`: a `pending` backfill means the scope has not caught up yet, not that there is nothing to recall. - `honcho start` does not rewrite `environmentUrl`. Use `HONCHO_BASE_URL=http://127.0.0.1:8000` to talk to local stack. ## Inspection tour When orienting to a Honcho deployment, walk outside-in: ### 1. Understand the workspace ```bash honcho workspace inspect --json ``` ### 2. Find the peer ```bash honcho peer list --json honcho peer inspect <peer_id> --json ``` ### 3. Check peer's memory ```bash honcho peer card <peer_id> --json honcho conclusion list --observer <peer_id> --json honcho conclusion search "topic" --observer <peer_id> --json ``` ### 4. Debug a session ```bash honcho session inspect <session_id> --json honcho session view <session_id> --last 20 --json honcho session view <session_id> --page 2 --size 50 --json honcho message list <session_id> --last 20 --json honcho session context <session_id> --json honcho session summaries <session_id> --json ``` ### 5. Search across workspace ```bash honcho workspace search "query" --json honcho workspace chat "what themes show up across peers?" --json honcho workspace chat "what happened in this project?" --scope my-project --json honcho peer search <peer_id> "query" --json ``` ### 6. Bound recall with a scope ```bash honcho scope list --json honcho scope inspect <name> --json # members + backfill summary honcho scope create <name> --sessions <id1>,<id2> --json honcho scope status <name> --json # wait until nothing is pending honcho workspace chat "what happened here?" --scope <name> --json ``` ## Debugging playbook ### Peer not learning? ```bash # Is observation enabled? honcho peer inspect <peer_id> --json | jq '.configuration' # What conclusions exist? honcho conclusion list --observer <peer_id> --json honcho conclusion search "expected topic" --observer <peer_id> --json ``` ### Session context looks wrong? ```bash # Raw context an agent would receive honcho session context <session_id> --json # Summaries feeding the context honcho session summaries <session_id> --json # Recent message history honcho message list <session_id> --last 50 --json ``` ### Dialectic giving bad answers? ```bash # What the peer card says honcho peer card <peer_id> --json # Conclusions on the specific topic honcho conclusion search "topic" --observer <peer_id> --json # Exercise the dialectic directly honcho peer chat <peer_id> "what do you know about X?" --json honcho peer chat <peer_id> "what happened here?" --scope my-project --json honcho workspace chat "what themes show up across peers?" --json ```