Install
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 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:
Configuration
The CLI resolves config in this order: flag → env var → config file → default.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.
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 orHONCHO_* env vars on every invocation.
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). --jsonflag /HONCHO_JSON=1— force JSON regardless of terminal.
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:
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
delete
delete
derived
derived
get
get
list
list
honcho config
Inspect CLI configuration.honcho doctor
Verify config and connectivity. Scope with -w / -p to check workspace, peer, and queue health.honcho dream
List dreams and inspect what each one changed in a peer’s representation.inspect
inspect
Show what one dream changed.Lists the conclusions it created, each with the conclusions it was derived
from; the conclusions it removed, as they read when removed; and the peer
card before and after. Each source shows where it stands now: current,
removed (and by which dream), or unavailable once deleted or removed longer
ago than history is kept.
list
list
List dreams in the workspace, newest first.Pass -p to see the dreams about one peer, and —observer to narrow to one
observer’s model of that peer.
honcho dream inspect \<id> shows what a
dream changed.honcho help
Show help message.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 API URL (e.g. https://api.honcho.dev, http://localhost:8000).
honcho install
Find the AI agents on this machine and add Honcho to them. Claude Code, Hermes, OpenClaw and Pi get their Honcho plugin, and Codex the Honcho MCP server and skill, each through the agent’s own commands and the API key in ~/.honcho/config.json. Other agents link to their setup guide.honcho message
List, create, and get messages within a session.create
create
honcho peer
List, create, chat with, search, and manage peers and their representations.chat
chat
Query the dialectic about a peer.
Recall only from this scope. Repeat or comma-separate for several (explicit conclusions only). Excludes -s and —sessions.
Recall only from these session IDs (repeat or comma-separate); explicit conclusions only. Excludes -s and —scope.
create
create
list
list
List all peers in the workspace.
representation
representation
honcho scope
List, create, inspect, and manage scopes — named session sets that bound recall.add-sessions
add-sessions
create
create
list
list
List scopes in the workspace.
remove-session
remove-session
honcho session
List, inspect, view, create, delete, and manage conversation sessions and their peers.context
context
create
create
delete
delete
representation
representation
set-metadata
set-metadata
view
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
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.
Interactive config wizard: basic (provider/model) or advanced (embeddings, deriver, dialectic, dreams, flush).
honcho status
Show local stack endpoints and container health. With no--profile, lists every stack under ~/.honcho/profiles/.
honcho stop
Stop the local stack started byhoncho start. Keeps data unless —wipe.
honcho workspace
List, create, inspect, chat, delete, and search workspaces.chat
chat
Query the dialectic across all peers in the workspace.
Recall only from this scope. Repeat or comma-separate for several (explicit conclusions only). Excludes -s.
delete
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.
list
list
List all accessible workspaces.
replay
replay
Replay a workspace’s sessions into another workspace, on this or another instance.Copies workspace, peer and session settings, then re-sends every message in
order with its original timestamp. The destination derives its own
conclusions; conclusions and peer cards are not copied, so the ones written
through the API are not recreated. Rerunning resumes: messages already in
the destination are skipped.Each side uses the configured instance unless its URL is given. A side on
another instance needs its own API key, read from HONCHO_FROM_API_KEY /
HONCHO_TO_API_KEY; the configured credentials are never sent to it.
Destination workspace ID. Defaults to the —from ID, which needs a different destination instance.
Source Honcho URL, when it is not the configured instance. Its API key is read from HONCHO_FROM_API_KEY.
Destination Honcho URL, when it is not the configured instance. Its API key is read from HONCHO_TO_API_KEY.
honcho peer chat covers peer chat only. Workspace chat has no CLI command yet; use the API or SDKs.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.1
Survey the workspace
2
Inspect a specific peer
3
Review the peer's memory
4
See what dreams changed
5
Debug a session
A peer isn’t learning
If new messages aren’t producing new conclusions, work down the diagnostic ladder.Session context looks wrong
When an agent’s responses don’t reflect what you expect it to know.Dialectic returns bad answers
Whenhoncho peer chat, honcho workspace chat, or the dialectic API is hallucinating or missing context.
Copy a workspace to another workspace or instance
honcho workspace replay copies settings and membership, then re-sends every
message in order with its original timestamp. The destination runs its own
reasoning over those messages, so its conclusions, summaries and peer cards are
derived fresh and can differ from the source. Conclusions and peer cards are
not copied. Use it to copy a workspace inside one instance, or to move one
between instances, for example from managed Honcho to a self-hosted instance.
--from-url / --to-url names
another one, so with the CLI set up for managed Honcho (https://api.honcho.dev)
only the self-hosted side needs a URL. --to defaults to the --from ID, so the
copy keeps its name on the other instance.
A side on another instance authenticates only with its own key, and your
configured credentials are never sent to it. A self-hosted instance with
authentication off needs no key. If authentication is on, pass that instance’s
key:
HONCHO_FROM_API_KEY when the other instance is the source. The keys are
read from the environment only. There is no flag for them, because command-line
arguments are visible in process listings. A key typed in an export line is
still saved in your shell history, so load it from a secrets manager or a file
where you can.
A workspace-scoped key is enough for the source. Such a key cannot list
workspaces, so it cannot tell an empty workspace from a missing one: if the
source has no sessions and no peers, the command stops with NOTHING_TO_REPLAY
and creates nothing.
Things to know:
- Dry-run first.
--dry-runreads both sides and writes nothing, not even the destination workspace. For each session it says whether a replay will create it, resume it, find it up to date, or skip it because the destination already has different messages under that session ID (a conflict). - It costs reasoning on the destination. Every replayed message is derived again. Derivation runs in the background after the command exits; the summary prints the
honcho workspace queue-statuscommand that shows its progress. - It resumes. Rerun the same command after an interruption; messages already in the destination are skipped. A session in conflict is left untouched, listed under
failedwith the reasonconflict, and the command exits non-zero. Other failures have the reasonerrorand are retried by a rerun. - Output. In a terminal you get a short report. With
--json, or when stdout is not a terminal, you get one JSON object with the same facts. Progress lines go to stderr in both modes. A dry run and a replay report different fields:- Both:
source,destination,sessions_in_source,workspace_settings_copied,not_copiedandsessions. - Dry run only:
dry_run,sessions_to_replay,actions(how many sessions arecreate,resume,up_to_dateorconflict),messages_in_sessions,messages_to_send,peers_to_copyandpeers_in_destination.sessionshas one entry per selected session, with itsaction,messages_in_destinationandmessages_to_send. - Replay only:
sessions_replayed,sessions_failed,actions(how many sessions werecreated,resumedorup_to_date),messages_created,messages_skipped,peers_created,peers_existing,failed,elapsed_secondsandcheck_derivation.sessionslists only the sessions that were replayed, each with itsaction,messages_createdandmessages_skipped. A session that was not replayed is infailedinstead, with itssession_id,reasonanderror, so read both lists.check_derivationis the queue command, ornullwhen the replay sent no messages, as on a rerun that finds everything up to date.
- Both:
- Memory written through the API is not copied. Conclusions and peer cards are never copied; the destination derives its own from the messages. Conclusions you created through the conclusions API and peer cards you set yourself have no source message, so the destination cannot derive them again. Both reports say how many conclusions the source holds (
not_copied.conclusions_in_sourcein JSON). Honcho does not mark which conclusions were written through the API, so that number counts all of them. Copy the ones you wrote yourself after the replay. - Settings are copied as they are now. Messages sent under older observer settings or custom instructions are derived under the current ones. Per-message configuration is not stored by Honcho, so it is not replayed.
- Session membership is copied as it is now, not as it changed over time. Honcho’s API does not return when a peer joined or left a session, so the destination session has the source’s current members from its first message. A peer that joined late and observes others also observes the messages sent before it joined. The destination then derives conclusions the source never had, and they add to the reasoning cost. A peer that has left a session does not observe it in the destination, so the conclusions it formed there about other peers are not derived again.
- Existing peers and sessions with the same ID take the source’s metadata and configuration. Workspace-level settings are copied only when the destination has no sessions yet.
- IDs change. Messages get new IDs, and sessions and peers get the replay time as their
created_at.
Scripting & automation
Pipe commands intojq for inline transforms, or set HONCHO_* env vars for a CI/CD environment with no config file: