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

honcho workspace inspect --json

2. Find the peer

honcho peer list --json
honcho peer inspect <peer_id> --json

3. Check peer's memory

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

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

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

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?

# 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?

# 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?

# 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