CLI Reference

Install

uv tool install honcho-cli

uvx honcho-cli

This only installs the honcho command. It does not start a server. Use honcho start --setup (Docker + an LLM provider key) when you want a local stack.

Quick Start

honcho init                 # Honcho API key or browser login + server URL (talk *to* Honcho)
honcho start --setup basic  # local stack: LLM provider key + Docker (not set by init)
honcho doctor               # verify your config + connectivity
honcho                      # show banner + command list

honcho init authenticates the CLI against a Honcho server. It does not configure the LLM key a local stack needs — that is honcho start --setup.

Local stack

honcho start --setup basic is the fastest way to run Honcho on your machine. It does not require cloning the Honcho repo. The wizard prompts for an LLM provider and API key, writes them into the profile .env, pulls ghcr.io/plastic-labs/honcho:latest, pins that digest, and starts API + deriver + Postgres + Redis via Docker. Default profile is local (--profile / HONCHO_PROFILE). First start copies the image config.toml.example into the profile directory; later starts leave that file alone so your edits persist — including when you re-pin the image. Delete config.toml yourself if you want a fresh copy from a new image. Pass --image to pin a different tag or digest. Ports bind to 127.0.0.1; if 8000/5432/6379 are taken, the CLI remaps them (or pass --api-port / --db-port / --redis-port). Auth is off (AUTH_USE_AUTH=false). Pass --setup basic or --setup advanced for an interactive wizard that writes curated LLM/feature overrides into the profile .env (environment variables win over config.toml). This is TTY-only. basic covers provider and chat model; advanced also covers embeddings, deriver/dialectic models, dreams, and deriver flush. Re-running --setup while the stack is up recreates the API and deriver containers. This does not change environmentUrl in the shared config file. To talk to the local stack:

HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list
honcho init --base-url http://127.0.0.1:8000   # persist local as the CLI default

honcho start --setup basic
honcho start --setup advanced
LLM_OPENAI_API_KEY=sk-... honcho start   # skip the wizard if the key is already in the env
honcho status
honcho stop            # keep data
honcho stop --wipe     # also delete volumes

To develop the server (live reload, from-source image), see Local Environment Setup.

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
Update nag	—	`HONCHO_NO_UPDATE_CHECK`	—	No
Local stack	—	`HONCHO_PROFILE`	`--profile`	No

Persisted config

The CLI shares ~/.honcho/config.json with sibling Honcho tools. It owns apiKey and environmentUrl at the top level — everything else (hosts, sessions, etc.) is written by other tools and left untouched on save. On managed servers that advertise the device grant in OAuth metadata, honcho init can log you in via the browser; tokens auto-refresh and are stored under oauth without deleting a shared apiKey.

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

Per-command targeting (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 targeting 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.

Interactive sessions may print a one-line upgrade hint on stderr at most once a day when a newer honcho-cli is on PyPI (uv tool upgrade honcho-cli). JSON/piped output skips it; set HONCHO_NO_UPDATE_CHECK=1 to disable it. 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, view, 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

view

View a session transcript as a chat log.Modes (pick one):

default / —last N: tail of the conversation (most recent N)
—page N [—size M]: page through the full transcript
—all: every message

Paging follows the requested order: —page 1 starts at the oldest message, or the newest with —reverse.Human mode prints a row-delimited table. JSON mode emits the message list (same shape as message list).

honcho session view [<session_id>]

string

number

Show only the N most recent messages (default when no —page/—all: 50).

number

1-indexed page of the full transcript. Use for page 2+.

number

Messages per page; requires —page (1-100, default: 50).

boolean

Show the full transcript (every page).

boolean

Newest first (default is chronological: oldest at top).

boolean

Include message IDs in the transcript.

string

Filter by peer ID. Short alias: -p.

honcho start

Start a local Honcho stack (API, deriver, Postgres, Redis). Requires Docker. Uses cloud LLM providers. Does not change the CLI’s configured server URL — pass HONCHO_BASE_URL to talk to this stack. --setup basic or --setup advanced runs an interactive config wizard.

honcho start

string

default:"local"

Local stack profile name.

string

Host port for the API.

string

Host port for Postgres.

string

Host port for Redis.

string

Interactive config wizard: basic (provider/model) or advanced (embeddings, deriver, dialectic, dreams, flush).

string

Honcho image to pull and pin by digest (default: ghcr.io/plastic-labs/honcho:latest).

string

default:"180"

Seconds to wait for /health after compose up.

honcho status

Show local stack endpoints and container health. With no --profile, lists every stack under ~/.honcho/profiles/.

honcho status

string

Limit to this profile. Omit to show every local stack.

honcho stop

Stop the local stack started by honcho start. Keeps data unless —wipe.

honcho stop

string

default:"local"

Local stack profile name.

boolean

Also delete volumes (Postgres data).

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 session view <session_id> --last 20
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. honcho session view shows the raw transcript that context was built from; it prints content verbatim, so tag-delimited and multi-line messages appear exactly as stored.

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 session view <session_id> --last 50

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

Local stack

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 start

honcho status

honcho stop

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

​Local stack

​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 start

​honcho status

​honcho stop

​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

Local stack

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 start

honcho status

honcho stop

honcho workspace

Workflows

Inspect an unfamiliar workspace

A peer isn’t learning

Session context looks wrong

Dialectic returns bad answers

Scripting & automation