CLI Reference

Install

uv tool install 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>

content

string

required

--observer

string

Observer peer ID.

--observed

string

Observed peer ID.

--session

string

Session context. Short alias: -s.

delete

Delete a conclusion.

honcho conclusion delete <conclusion_id>

conclusion_id

string

required

--observer

string

Observer peer ID.

--observed

string

Observed peer ID.

--yes

boolean

Skip confirmation. Short alias: -y.

list

List conclusions.

honcho conclusion list

--observer

string

Observer peer ID.

--observed

string

Observed peer ID.

--limit

number

default:"10"

Max results.

Semantic search over conclusions.

honcho conclusion search <query>

query

string

required

--observer

string

Observer peer ID.

--observed

string

Observed peer ID.

--top-k

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

--api-key

string

API key (admin JWT).

--base-url

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>

content

string

required

--peer

string

required

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

--metadata

string

JSON metadata to associate with the message.

--session

string

Session ID. Short alias: -s.

get

Get a single message by ID.

honcho message get <message_id>

message_id

string

required

--session

string

Session ID. Short alias: -s.

list

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

honcho message list [<session_id>]

session_id

string

--last

number

default:"20"

Number of recent messages.

--reverse

boolean

Show oldest first (default is newest first).

--brief

boolean

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

--peer

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>]

peer_id

string

--target

string

Target peer for relationship card.

chat

Query the dialectic about a peer.

honcho peer chat <query>

query

string

required

--target

string

Target peer for perspective.

--reasoning

string

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

create

Create or get a peer.

honcho peer create <peer_id>

peer_id

string

required

--observe-me

boolean

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

--metadata

string

JSON metadata to associate with the peer.

get-metadata

Get metadata for a peer.

honcho peer get-metadata [<peer_id>]

peer_id

string

inspect

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

honcho peer inspect [<peer_id>]

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>]

peer_id

string

--target

string

Target peer to get representation about.

--search-query

string

Semantic search query to filter conclusions.

--max-conclusions

number

Maximum number of conclusions to include.

Search a peer’s messages.

honcho peer search <query>

query

string

required

--limit

number

default:"10"

Max results.

set-metadata

Set metadata for a peer.

honcho peer set-metadata <metadata>

metadata

string

required

--peer

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>

session_id

string

required

peer_ids

string

required

context

Get session context (what an agent would see).

honcho session context [<session_id>]

session_id

string

--tokens

number

Token budget.

--summary

boolean

default:"true"

Include summary. Negate with --no-summary.

create

Create or get a session.

honcho session create <session_id>

session_id

string

required

--peers

string

Comma-separated peer IDs to add to the session.

--metadata

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>]

session_id

string

--yes

boolean

Skip confirmation. Short alias: -y.

get-metadata

Get metadata for a session.

honcho session get-metadata [<session_id>]

session_id

string

inspect

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

honcho session inspect [<session_id>]

session_id

string

list

List sessions in the workspace.

honcho session list

--peer

string

Filter by peer. Short alias: -p.

peers

List peers in a session.

honcho session peers [<session_id>]

session_id

string

remove-peers

Remove peers from a session.

honcho session remove-peers <session_id> <peer_ids>

session_id

string

required

peer_ids

string

required

representation

Get the representation of a peer within a session.

honcho session representation <peer_id> [<session_id>]

peer_id

string

required

session_id

string

--target

string

Target peer (what peer_id knows about target).

--search-query

string

Semantic search query to filter conclusions.

--max-conclusions

number

Maximum number of conclusions to include.

Search messages in a session.

honcho session search <query> [<session_id>]

query

string

required

session_id

string

--limit

number

default:"10"

Max results.

set-metadata

Set metadata for a session.

honcho session set-metadata [<session_id>]

session_id

string

--data

string

required

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

summaries

Get session summaries (short + long).

honcho session summaries [<session_id>]

session_id

string

honcho workspace

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

create

Create or get a workspace.

honcho workspace create <workspace_id>

workspace_id

string

required

--metadata

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>

workspace_id

string

required

--yes

boolean

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

--cascade

boolean

Delete all sessions before deleting the workspace.

--dry-run

boolean

Show what would be deleted without deleting.

inspect

Inspect a workspace: peers, sessions, config.

honcho workspace inspect [<workspace_id>]

workspace_id

string

list

List all accessible workspaces.

honcho workspace list

queue-status

Get queue processing status.

honcho workspace queue-status

--observer

string

Filter by observer peer.

--sender

string

Filter by sender peer.

Search messages across workspace.

honcho workspace search <query>

query

string

required

--limit

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

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