Skip to main content

Install

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 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:
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.

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 or HONCHO_* 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).
  • --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:
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 a conclusion.
string
required
string
Observer peer ID.
string
Observed peer ID.
string
Session context. Short alias: -s.
Delete a conclusion.
string
required
string
Observer peer ID.
string
Observed peer ID.
boolean
Skip confirmation. Short alias: -y.
List the conclusions derived FROM a conclusion.Walks the reasoning tree upward (premise -> conclusion); conclusion get on a conclusion’s source_ids walks it downward. Worth checking before deleting or correcting a fact.
string
required
number
default:"10"
Max results.
Fetch conclusions by ID, from anywhere in the workspace.Pass a conclusion’s source_ids to see the premises it was derived from, and repeat to walk a reasoning chain down to the explicit facts it rests on. IDs that no longer exist are reported rather than failing the command.
string
required
List conclusions.
string
Observer peer ID.
string
Observed peer ID.
number
default:"10"
Max results.
string
Only this reasoning level: explicit, deductive, inductive, contradiction.
string
Only conclusions derived from this conclusion ID.
string
Only explicit conclusions that cite this message ID as evidence.
Semantic search over conclusions.
string
required
string
Observer peer ID.
string
Observed peer ID.
number
default:"10"
Max results.
string
Only this reasoning level: explicit, deductive, inductive, contradiction.

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.
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.
string
required
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.
string
Only dreams from this observer’s perspective (with -p: one representation).
number
default:"20"
Dreams per page.
number
default:"1"
Page number, newest dreams first.
string
Only dreams about this peer (the observed peer). Short alias: -p.

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.
string
API key (admin JWT).
string

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.
string
boolean
Only show what was found; install nothing.

honcho message

List, create, and get messages within a session.
Create a message in a session.
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 a single message by ID.
string
required
string
Session ID. Short alias: -s.
List messages in a session. Scoped to a peer with -p.
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.
Get raw peer card content.
string
string
Target peer for relationship card.
Query the dialectic about a peer.
string
required
string
Target peer for perspective.
string
Reasoning level: minimal, low, medium, high, max. Short alias: -r.
string
Recall only from this scope. Repeat or comma-separate for several (explicit conclusions only). Excludes -s and —sessions.
string
Recall only from these session IDs (repeat or comma-separate); explicit conclusions only. Excludes -s and —scope.
boolean
Also report what the answer was built from: the conclusions and messages read and the tools called.
Create or get a peer.
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 for a peer.
string
Inspect a peer: card, session count, recent conclusions.
string
List all peers in the workspace.
Get the formatted representation for a peer.
string
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.
string
required
number
default:"10"
Max results.
Set metadata for a peer.
string
required
string
Peer ID (uses default if omitted). Short alias: -p.

honcho scope

List, create, inspect, and manage scopes — named session sets that bound recall.
Add existing sessions to a scope. History is backfilled asynchronously — poll honcho scope status.
string
required
string
required
Create or get a scope, optionally adding sessions to it.
string
required
string
Sessions to add (repeat or comma-separate). History backfills asynchronously; see honcho scope status.
string
JSON metadata to associate with the scope.
Inspect a scope: metadata, member sessions, and backfill state.
string
required
List scopes in the workspace.
Remove a session from a scope. Its conclusions are reconciled out asynchronously.
string
required
string
required
List the sessions that are members of a scope (longest-standing first).
string
required
Per-session backfill state. Recall through the scope is complete once nothing is pending.
string
required

honcho session

List, inspect, view, create, delete, and manage conversation sessions and their peers.
Add peers to a session.
string
required
string
required
Get session context (what an agent would see).
string
number
Token budget.
boolean
default:"true"
Include summary. Negate with --no-summary.
Create or get a session.
string
required
string
Comma-separated peer IDs to add to the session.
string
JSON metadata to associate with the session.
Delete a session and all its data. Destructive — requires —yes or interactive confirm.
string
boolean
Skip confirmation. Short alias: -y.
Get metadata for a session.
string
Inspect a session: peers, message count, summaries, config.
string
List sessions in the workspace.
string
Filter by peer. Short alias: -p.
List peers in a session.
string
Remove peers from a session.
string
required
string
required
Get the representation of a peer within a session.
string
required
string
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.
string
required
string
number
default:"10"
Max results.
Set metadata for a session.
string
string
required
JSON metadata to set (e.g. ’{“key”: “value”}’). Short alias: -d.
Get session summaries (short + long).
string
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).
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.
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/.
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.
string
default:"local"
Local stack profile name.
boolean
Also delete volumes (Postgres data).

honcho workspace

List, create, inspect, chat, delete, and search workspaces.
Query the dialectic across all peers in the workspace.
string
required
string
Reasoning level: minimal, low, medium, high, max. Short alias: -r.
string
Recall only from this scope. Repeat or comma-separate for several (explicit conclusions only). Excludes -s.
boolean
Also report what the answer was built from: the conclusions and messages read and the tools called.
Create or get a workspace.
string
required
string
JSON metadata to associate with the workspace.
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.
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 a workspace: peers, sessions, config.
string
List all accessible workspaces.
Get queue processing status.
string
Filter by observer peer.
string
Filter by sender peer.
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.
string
required
Source workspace ID.
string
Destination workspace ID. Defaults to the —from ID, which needs a different destination instance.
string
Source Honcho URL, when it is not the configured instance. Its API key is read from HONCHO_FROM_API_KEY.
string
Destination Honcho URL, when it is not the configured instance. Its API key is read from HONCHO_TO_API_KEY.
string
Replay only the N sessions with the most recent message.
boolean
Show what a replay would do with each session, without writing anything.
Search messages across workspace.
string
required
number
default:"10"
Max results.
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

Each dream lists the conclusions it created with what each was derived from, the conclusions it removed, and the peer card before and after.
5

Debug a session

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.

Session context looks wrong

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

Dialectic returns bad answers

When honcho 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.
Each side uses the configured instance unless --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:
Use 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-run reads 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-status command 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 failed with the reason conflict, and the command exits non-zero. Other failures have the reason error and 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_copied and sessions.
    • Dry run only: dry_run, sessions_to_replay, actions (how many sessions are create, resume, up_to_date or conflict), messages_in_sessions, messages_to_send, peers_to_copy and peers_in_destination. sessions has one entry per selected session, with its action, messages_in_destination and messages_to_send.
    • Replay only: sessions_replayed, sessions_failed, actions (how many sessions were created, resumed or up_to_date), messages_created, messages_skipped, peers_created, peers_existing, failed, elapsed_seconds and check_derivation. sessions lists only the sessions that were replayed, each with its action, messages_created and messages_skipped. A session that was not replayed is in failed instead, with its session_id, reason and error, so read both lists. check_derivation is the queue command, or null when the replay sent no messages, as on a rerun that finds everything up to date.
  • 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_source in 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 into jq for inline transforms, or set HONCHO_* env vars for a CI/CD environment with no config file:
Non-interactive onboarding: