CLI Reference

Install

uv tool install honcho-cli

uvx honcho-cli

Quick Start

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

Configuration

The CLI resolves config in this order: flag → env var → config file → default.

Value	File key	Env var	Flag	Persisted?
API key	`apiKey`	`HONCHO_API_KEY`	—	Yes
API URL	`environmentUrl`	`HONCHO_BASE_URL`	—	Yes
Workspace	—	`HONCHO_WORKSPACE_ID`	`-w` / `--workspace`	No
Peer	—	`HONCHO_PEER_ID`	`-p` / `--peer`	No
Session	—	`HONCHO_SESSION_ID`	`-s` / `--session`	No
JSON output	—	`HONCHO_JSON`	`--json`	No

Persisted config

The CLI shares ~/.honcho/config.json with sibling Honcho tools. It owns only apiKey and environmentUrl at the top level — everything else (hosts, sessions, etc.) is written by other tools and left untouched on save.

{
  "apiKey": "hch-v3-...",
  "environmentUrl": "https://api.honcho.dev",
  "hosts": { "claude_code": { "...": "..." } }
}

Per-command scoping (workspace / peer / session) is handled via -w / -p / -s flags or HONCHO_* env vars. Not persisted as CLI defaults. This is deliberate: every invocation is explicit about what it operates on.

Runtime overrides

Workspace, peer, and session scoping are per-command only — pass flags or HONCHO_* env vars on every invocation.

# Per-command flags
honcho peer card -w prod -p user

# Or export once per shell
export HONCHO_WORKSPACE_ID=prod
export HONCHO_PEER_ID=user
honcho peer card

# One-off against a different server
HONCHO_BASE_URL=http://localhost:8000 honcho workspace list

# CI/CD — env vars only, no config file needed
export HONCHO_API_KEY=hch-v3-xxx
export HONCHO_BASE_URL=https://api.honcho.dev
honcho workspace list

Output & exit codes

Every command adapts its output to the context:

TTY — human-readable tables via Rich.
Piped or redirected — JSON automatically (detected via isatty).
--json flag / HONCHO_JSON=1 — force JSON regardless of terminal.

Collection commands emit JSON arrays; single-resource commands emit JSON objects. Errors are always structured:

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

Exit code	Meaning
`0`	Success
`1`	Client error (bad input, resource not found)
`2`	Server error
`3`	Auth error (missing or invalid API key)

CI pipelines and agent runtimes can branch on these without parsing stderr.

Command reference

honcho conclusion

List, search, create, and delete peer conclusions (Honcho’s memory atoms).

create

Create a conclusion.

honcho conclusion create <content>

string

required

string

Observer peer ID.

string

Observed peer ID.

string

Session context. Short alias: -s.

delete

Delete a conclusion.

honcho conclusion delete <conclusion_id>

string

required

string

Observer peer ID.

string

Observed peer ID.

boolean

Skip confirmation. Short alias: -y.

list

List conclusions.

honcho conclusion list

string

Observer peer ID.

string

Observed peer ID.

number

default:"10"

Max results.

Semantic search over conclusions.

honcho conclusion search <query>

string

required

string

Observer peer ID.

string

Observed peer ID.

number

default:"10"

Max results.

honcho config

Inspect CLI configuration.

honcho config

honcho doctor

Verify config and connectivity. Scope with -w / -p to check workspace, peer, and queue health.

honcho doctor

honcho help

Show help message.

honcho help

honcho init

Set API key and server URL in ~/.honcho/config.json. Press Enter to keep the current value or type a replacement. Workspace / peer / session scoping is per-command via -w / -p / -s or HONCHO_* env vars — never persisted.

honcho init

string

API key (admin JWT).

string

Honcho API URL (e.g. https://api.honcho.dev, http://localhost:8000).

honcho message

List, create, and get messages within a session.

create

Create a message in a session.

honcho message create <content>

string

required

string

required

Peer ID of the message sender. Short alias: -p.

string

JSON metadata to associate with the message.

string

Session ID. Short alias: -s.

get

Get a single message by ID.

honcho message get <message_id>

string

required

string

Session ID. Short alias: -s.

list

List messages in a session. Scoped to a peer with -p.

honcho message list [<session_id>]

string

number

default:"20"

Number of recent messages.

boolean

Show oldest first (default is newest first).

boolean

Show only IDs, peer, token count, and created_at (no content).

string

Filter by peer ID. Short alias: -p.

honcho peer

List, create, chat with, search, and manage peers and their representations.

card

Get raw peer card content.

honcho peer card [<peer_id>]

string

Target peer for relationship card.

chat

Query the dialectic about a peer.

honcho peer chat <query>

string

required

string

Target peer for perspective.

string

Reasoning level: minimal, low, medium, high, max. Short alias: -r.

create

Create or get a peer.

honcho peer create <peer_id>

string

required

boolean

Whether Honcho will form a representation of this peer. Negate with --no-observe-me.

string

JSON metadata to associate with the peer.

get-metadata

Get metadata for a peer.

honcho peer get-metadata [<peer_id>]

string

inspect

Inspect a peer: card, session count, recent conclusions.

honcho peer inspect [<peer_id>]

string

list

List all peers in the workspace.

honcho peer list

representation

Get the formatted representation for a peer.

honcho peer representation [<peer_id>]

string

Target peer to get representation about.

string

Semantic search query to filter conclusions.

number

Maximum number of conclusions to include.

Search a peer’s messages.

honcho peer search <query>

string

required

number

default:"10"

Max results.

set-metadata

Set metadata for a peer.

honcho peer set-metadata <metadata>

string

required

string

Peer ID (uses default if omitted). Short alias: -p.

honcho session

List, inspect, create, delete, and manage conversation sessions and their peers.

add-peers

Add peers to a session.

honcho session add-peers <session_id> <peer_ids>

string

required

string

required

context

Get session context (what an agent would see).

honcho session context [<session_id>]

string

number

Token budget.

boolean

default:"true"

Include summary. Negate with --no-summary.

create

Create or get a session.

honcho session create <session_id>

string

required

string

Comma-separated peer IDs to add to the session.

string

JSON metadata to associate with the session.

delete

Delete a session and all its data. Destructive — requires —yes or interactive confirm.

honcho session delete [<session_id>]

string

boolean

Skip confirmation. Short alias: -y.

get-metadata

Get metadata for a session.

honcho session get-metadata [<session_id>]

string

inspect

Inspect a session: peers, message count, summaries, config.

honcho session inspect [<session_id>]

string

list

List sessions in the workspace.

honcho session list

string

Filter by peer. Short alias: -p.

peers

List peers in a session.

honcho session peers [<session_id>]

string

remove-peers

Remove peers from a session.

honcho session remove-peers <session_id> <peer_ids>

string

required

string

required

representation

Get the representation of a peer within a session.

honcho session representation <peer_id> [<session_id>]

string

required

string

Target peer (what peer_id knows about target).

string

Semantic search query to filter conclusions.

number

Maximum number of conclusions to include.

Search messages in a session.

honcho session search <query> [<session_id>]

string

required

string

number

default:"10"

Max results.

set-metadata

Set metadata for a session.

honcho session set-metadata [<session_id>]

string

required

JSON metadata to set (e.g. ’{“key”: “value”}’). Short alias: -d.

summaries

Get session summaries (short + long).

honcho session summaries [<session_id>]

string

honcho workspace

List, create, inspect, delete, and search workspaces.

create

Create or get a workspace.

honcho workspace create <workspace_id>

string

required

string

JSON metadata to associate with the workspace.

delete

Delete a workspace. Use —dry-run first to see what will be deleted.Requires —yes to skip confirmation, or will prompt interactively. If sessions exist, requires —cascade to delete them first.

honcho workspace delete <workspace_id>

string

required

boolean

Skip confirmation prompt (for scripted/agent use). Short alias: -y.

boolean

Delete all sessions before deleting the workspace.

boolean

Show what would be deleted without deleting.

inspect

Inspect a workspace: peers, sessions, config.

honcho workspace inspect [<workspace_id>]

string

list

List all accessible workspaces.

honcho workspace list

queue-status

Get queue processing status.

honcho workspace queue-status

string

Filter by observer peer.

string

Filter by sender peer.

Search messages across workspace.

honcho workspace search <query>

string

required

number

default:"10"

Max results.

Workflows

Inspect an unfamiliar workspace

When you pick up a workspace and need to orient — start broad, narrow to the peer and session you care about.

Survey the workspace

honcho workspace inspect --json
honcho peer list --json

Inspect a specific peer

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

Review the peer's memory

honcho conclusion list --observer <peer_id> --json
honcho conclusion search "topic" --observer <peer_id> --json

Debug a session

honcho session inspect <session_id> --json
honcho message list <session_id> --last 20 --json
honcho session context <session_id> --json
honcho session summaries <session_id> --json

honcho session context shows exactly what an agent would receive at inference time — check it before honcho peer chat if a response surprises you.

A peer isn’t learning

If new messages aren’t producing new conclusions, work down the diagnostic ladder.

# Is observation enabled for this peer?
honcho peer inspect <peer_id> --json | jq '.configuration'

# Is the deriver actually processing?
honcho workspace queue-status --json

# Do any conclusions exist at all? Any for the expected topic?
honcho conclusion list --observer <peer_id> --json
honcho conclusion search "expected topic" --observer <peer_id> --json

Session context looks wrong

When an agent’s responses don’t reflect what you expect it to know.

honcho session context <session_id> --json
honcho session summaries <session_id> --json
honcho message list <session_id> --last 50 --json

Dialectic returns bad answers

When honcho peer chat or the dialectic API is hallucinating or missing context.

# What does the peer card actually say?
honcho peer card <peer_id> --json

# Any conclusions for this topic?
honcho conclusion search "topic" --observer <peer_id> --json

# Reproduce the query against the CLI
honcho peer chat <peer_id> "what do you know about X?" --json

Scripting & automation

Pipe commands into jq for inline transforms, or set HONCHO_* env vars for a CI/CD environment with no config file:

# Pipe to jq
honcho peer list --json | jq '.[].id'
honcho workspace inspect --json | jq '.peers'

# Machine-parseable health check — exit code for CI, details for logs
honcho doctor --json

# CI/CD — env vars only, no ~/.honcho/config.json
export HONCHO_API_KEY=hch-v3-xxx
export HONCHO_BASE_URL=https://api.honcho.dev
honcho workspace list

Non-interactive onboarding:

# Pre-seed via flags / env vars; init still prompts for anything missing
HONCHO_API_KEY=hch-v3-xxx honcho init --base-url https://api.honcho.dev

Introduction

Core Concepts

Features

Reference

Install

Quick Start

Configuration

Persisted config

Runtime overrides

Output & exit codes

Command reference

honcho conclusion

honcho config

honcho doctor

honcho help

honcho init

honcho message

honcho peer

honcho session

honcho workspace

Workflows

Inspect an unfamiliar workspace

A peer isn’t learning

Session context looks wrong

Dialectic returns bad answers

Scripting & automation

​Install

​Quick Start

​Configuration

​Persisted config

​Runtime overrides

​Output & exit codes

​Command reference

​honcho conclusion

​honcho config

​honcho doctor

​honcho help

​honcho init

​honcho message

​honcho peer

​honcho session

​honcho workspace

​Workflows

​Inspect an unfamiliar workspace

​A peer isn’t learning

​Session context looks wrong

​Dialectic returns bad answers

​Scripting & automation

Install

Quick Start

Configuration

Persisted config

Runtime overrides

Output & exit codes

Command reference

honcho conclusion

honcho config

honcho doctor

honcho help

honcho init

honcho message

honcho peer

honcho session

honcho workspace

Workflows

Inspect an unfamiliar workspace

A peer isn’t learning

Session context looks wrong

Dialectic returns bad answers

Scripting & automation