honcho/honcho-cli/README.md

██╗  ██╗ ██████╗ ███╗   ██╗ ██████╗██╗  ██╗ ██████╗
██║  ██║██╔═══██╗████╗  ██║██╔════╝██║  ██║██╔═══██╗
███████║██║   ██║██╔██╗ ██║██║     ███████║██║   ██║
██╔══██║██║   ██║██║╚██╗██║██║     ██╔══██║██║   ██║
██║  ██║╚██████╔╝██║ ╚████║╚██████╗██║  ██║╚██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝

honcho-ai-cli

A terminal for Honcho — memory that reasons.

Install

As a standalone tool (recommended):

uv tool install honcho-ai-cli

As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project):

uv add honcho-ai[cli]
# or
pip install honcho-ai[cli]

Either way, you'll get the honcho command on your PATH.

Quick Start

honcho init        # confirm/set apiKey + environment in ~/.honcho/config.json
honcho doctor      # verify your config + connectivity
honcho             # show banner + command list

honcho init reads apiKey and environment from the top-level of ~/.honcho/config.json (the same file other Honcho tools — plugins, host integrations — share). If both are present, it confirms them with you; if either is missing (or you decline), it prompts for the missing value(s) and writes them back. Host-specific entries under hosts are left untouched.

Per-command scoping (workspace / peer / session) is handled via -w / -p / -s flags or HONCHO_* env vars — not persisted as CLI defaults.

Commands

Onboarding

Command	Description
honcho init	Confirm/set apiKey + environment in ~/.honcho/config.json
honcho doctor	Health check: config, connectivity, workspace, peer, queue

Workspaces

Command	Description
honcho workspace list	List accessible workspaces
honcho workspace inspect	Peers, sessions, config for a workspace
honcho workspace search <query>	Search messages across workspace
honcho workspace queue-status	Deriver queue processing status
honcho workspace delete <id>	Delete a workspace (--dry-run first)

Peers

Command	Description
honcho peer list	List peers in the workspace
honcho peer create <id>	Create or get a peer
honcho peer inspect <id>	Card, session count, recent conclusions
honcho peer card <id>	Raw peer card content
honcho peer chat <id> <query>	Query the dialectic about a peer
honcho peer representation <id>	Formatted representation
honcho peer search <id> <query>	Search a peer's messages
honcho peer get-metadata <id> / set-metadata	Metadata operations

Sessions

Command	Description
honcho session list	List sessions in the workspace
honcho session inspect <id>	Peers, message count, summaries, config
honcho session context <id>	What an agent would see
honcho session summaries <id>	Short + long summaries
honcho session peers <id> / add-peers / remove-peers	Peer management
honcho session search <id> <query>	Search messages in a session
honcho session representation <id>	Peer representation in a session
honcho session delete <id>	Destructive; requires --yes

Messages

Command	Description
honcho message list	List messages in a session
honcho message get <id>	Get a single message

Conclusions (observations)

Command	Description
honcho conclusion list	List conclusions
honcho conclusion search <query>	Semantic search
honcho conclusion create	Create a conclusion
honcho conclusion delete <id>	Delete a conclusion

Config

Command	Description
honcho config show	Show current config (API key redacted)

Agent Usage

All commands output JSON when stdout isn't a TTY, or when --json is forced:

honcho peer list --json
honcho workspace inspect --json | jq '.peers'
honcho doctor --json              # machine-parseable health checklist

Errors are structured:

{
  "error": {
    "code": "PEER_NOT_FOUND",
    "message": "Peer 'abc' not found in workspace 'my-ws'",
    "details": {"workspace_id": "my-ws", "peer_id": "abc"}
  }
}

Non-interactive onboarding:

# Pre-seed via flags / env vars; `honcho init` still prompts for anything missing
HONCHO_API_KEY=xxx honcho init --base-url local

Context Threading

Workspace / peer / session come from flags or env vars — not persisted defaults:

# Per-command flags
honcho --workspace prod --peer ajspig peer card

# Or export once per shell
export HONCHO_WORKSPACE_ID=prod
export HONCHO_PEER_ID=ajspig
honcho peer card
honcho peer inspect other_id     # positional arg still takes precedence

Environment Variables

Variable	Description
HONCHO_BASE_URL	API base URL pre-fill for honcho init only — ignored at runtime
HONCHO_API_KEY	Admin JWT pre-fill for honcho init only — ignored at runtime
HONCHO_WORKSPACE_ID	Default workspace
HONCHO_PEER_ID	Default peer
HONCHO_SESSION_ID	Default session
HONCHO_JSON	Force JSON output (1 / true)

Global Flags

Flag	Description
--json	Force JSON output
--quiet / -q	Suppress status messages
--workspace / -w	Override workspace ID
--peer / -p	Override peer ID
--session / -s	Override session ID
--version / -V	Show version

Configuration

The CLI shares ~/.honcho/config.json with sibling Honcho tools. It owns two top-level keys: apiKey and either environment ("local" / "production") or baseUrl (for custom deployments). Everything else at the top level — hosts, sessions, saveMessages, sessionStrategy, etc. — is left untouched.

Example:

{
  "apiKey": "hch-v3-...",
  "environment": "production",
  "hosts": { "claude_code": { "...": "..." } }
}

Precedence (highest first):

• apiKey: read only from ~/.honcho/config.json. No env-var fallback at runtime — a missing config file is a hard error. (honcho init still accepts --api-key / HONCHO_API_KEY as a one-time pre-fill for the write-to-file prompt.) This keeps a single, inspectable source of truth for authentication.
• base_url: CLI flag --base-url → HONCHO_BASE_URL → config file → default.
• workspace_id / peer_id / session_id: flag (-w / -p / -s) → env var (HONCHO_WORKSPACE_ID etc.). Not persisted to the config file.

Development

Install from source in editable mode so changes are picked up live:

git clone https://github.com/plastic-labs/honcho
cd honcho
uv tool install --force --editable --from ./honcho-cli honcho-ai-cli

Re-run any time — changes to honcho-cli/src/ are reflected immediately without reinstalling.

License

MIT