Name	Name	Last commit message	Last commit date
parent directory ..
scripts	scripts
src/honcho_cli	src/honcho_cli
tests	tests
CHANGELOG.md	CHANGELOG.md
README.md	README.md
pyproject.toml	pyproject.toml
uv.lock	uv.lock

██╗  ██╗ ██████╗ ███╗   ██╗ ██████╗██╗  ██╗ ██████╗
██║  ██║██╔═══██╗████╗  ██║██╔════╝██║  ██║██╔═══██╗
███████║██║   ██║██╔██╗ ██║██║     ███████║██║   ██║
██╔══██║██║   ██║██║╚██╗██║██║     ██╔══██║██║   ██║
██║  ██║╚██████╔╝██║ ╚████║╚██████╗██║  ██║╚██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝

honcho-cli

A terminal for Honcho — memory that reasons.

Install

As a standalone tool (recommended):

uv tool install honcho-cli

Quick Start

honcho init                 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
honcho start --setup basic  # local stack: LLM provider key + Docker
honcho doctor               # verify config + connectivity
honcho install              # find your AI agents and add Honcho to them
honcho                      # show banner + command list

honcho init writes apiKey and environmentUrl to the top-level of ~/.honcho/config.json (the same file other Honcho tools — plugins, host integrations — share) so the CLI can call a Honcho server. If both are present, it confirms them with you; if either is missing (or you decline), it prompts and writes them back. Host-specific entries under hosts are left untouched. It does not set the LLM provider key the local deriver needs — that is honcho start --setup (or LLM_*_API_KEY in the environment).

Per-command scoping (workspace / peer / session) is handled via -w / -p / -s flags or HONCHO_* env vars — not persisted as CLI defaults.

Local stack

honcho start --setup basic runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. The wizard writes the LLM provider key into the profile .env — honcho init cannot do this; its apiKey is for calling a Honcho server, not for deriver/dialectic inference. You can also pass LLM_OPENAI_API_KEY, LLM_ANTHROPIC_API_KEY, or LLM_GEMINI_API_KEY in the environment and skip --setup. Stack files live under ~/.honcho/profiles/local/ and are not committed to a project.

On first start, the CLI pulls ghcr.io/plastic-labs/honcho:latest and pins that digest in profile.json, then copies the image's config.toml.example to config.toml in the same directory. honcho start never overwrites config.toml after that — including when you re-pin the image. Delete the file yourself if you want a fresh copy from a new image.

Pass --setup basic or --setup advanced for an interactive wizard that writes curated LLM/feature overrides into the profile .env (env wins over config.toml). TTY only; re-runnable. basic asks provider + chat model; advanced also covers embeddings, deriver/dialectic models, dreams, and snappy deriver flush. Everything else stays in config.toml.

honcho start does not change environmentUrl in ~/.honcho/config.json (that file is shared with plugins). To talk to the local stack for one command:

HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list

To make local the default, run honcho init --base-url http://127.0.0.1:8000.

honcho start --setup basic
honcho start --setup advanced
honcho status
honcho stop            # keep data
honcho stop --wipe     # also delete volumes

Commands

Onboarding

Command	Description
`honcho init`	Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json`.
`honcho start`	Start a local Honcho stack (API, deriver, Postgres, Redis). Requires Docker and a cloud LLM key. `--setup basic` / `--setup advanced` runs an interactive config wizard (TTY only). Does not change `environmentUrl`.
`honcho stop`	Stop the local stack. `--wipe` also deletes volumes.
`honcho status`	Show every local stack (or `--profile` for one).
`honcho doctor`	Health check: config, connectivity, workspace, peer, queue
`honcho install`	Find the AI agents on this machine, show which already have Honcho, and pick which to add it to. Claude Code, Hermes, OpenClaw and Pi get their Honcho plugin and Codex the Honcho MCP server, each through the agent's own commands and the API key in `~/.honcho/config.json`. Other agents link to their setup guide; `honcho install grok-bot` copies a prompt to paste into a Grok Bot. `honcho install all` or `honcho install <id>...` skips the picker; `--list` only reports.

Workspaces

Command	Description
`honcho workspace list`	List accessible workspaces
`honcho workspace create <id>`	Create or get a workspace
`honcho workspace inspect`	Peers, sessions, config for a workspace
`honcho workspace chat <query>`	Query the dialectic across all peers (optional `-s` / `--scope` / `--reasoning`)
`honcho workspace search <query>`	Search messages across workspace
`honcho workspace queue-status`	Deriver queue status (filter with `--observer` / `--sender`)
`honcho workspace replay --from <id> --to <id>`	Copy a workspace by re-sending its messages, so the destination derives its own memory. `--to-url` / `--from-url` for another instance, `--num-sessions N` for the N most recently active sessions, `--dry-run` to preview
`honcho workspace delete <id>`	Delete a workspace. Use `--dry-run` to preview, `--cascade` to also delete sessions, `--yes` to skip the confirm prompt

Peers

Command	Description
`honcho peer list`	List peers in the workspace
`honcho peer create <id>`	Create or get a peer
`honcho peer inspect <id>`	Card, session count, recent conclusions
`honcho peer card <id>`	Raw peer card content
`honcho peer chat <query>`	Query the dialectic about a peer (peer via `-p` / `HONCHO_PEER_ID`; optional `--scope` / `--sessions`)
`honcho peer representation <id>`	Formatted representation
`honcho peer search <query>`	Search a peer's messages (peer via `-p` / `HONCHO_PEER_ID`)
`honcho peer get-metadata <id>` / `set-metadata`	Metadata operations

Sessions

Command	Description
`honcho session list`	List sessions in the workspace (filter with `--peer/-p`)
`honcho session create <id>`	Create or get a session (optionally `--peers` to add peers, `--metadata`)
`honcho session inspect <id>`	Peers, message count, summaries, config
`honcho session view <id>`	Transcript table (`--last N`, `--page N --size M`, `--all`, `--reverse`, `--ids`, `-p`)
`honcho session context <id>`	What an agent would see
`honcho session summaries <id>`	Short + long summaries
`honcho session peers <id>` / `add-peers` / `remove-peers`	Peer management
`honcho session search <id> <query>`	Search messages in a session
`honcho session representation <id>`	Peer representation in a session
`honcho session get-metadata <id>` / `set-metadata`	Metadata operations
`honcho session delete <id>`	Destructive; requires `--yes`

Scopes

Command	Description
`honcho scope list`	List scopes in the workspace
`honcho scope create <name>`	Create or get a scope (`--sessions id,...` to add members, `--metadata`)
`honcho scope inspect <name>`	Metadata, member sessions, backfill summary. Never creates a missing scope
`honcho scope sessions <name>`	Member sessions, longest-standing first
`honcho scope add-sessions <name> <ids...>` / `remove-session <name> <id>`	Membership; history backfills asynchronously
`honcho scope status <name>`	Per-session backfill state — recall is complete once nothing is `pending`

Messages

Command	Description
`honcho message list`	List messages in a session (session via `-s` / `HONCHO_SESSION_ID`)
`honcho message create <content>`	Create a message (requires `--peer/-p`, session via `-s`)
`honcho message get <id>`	Get a single message (session via `-s` / `HONCHO_SESSION_ID`)

Conclusions (observations)

Command	Description
`honcho conclusion list`	List conclusions (filter with `--observer` / `--observed`)
`honcho conclusion search <query>`	Semantic search (filter with `--observer` / `--observed`)
`honcho conclusion create`	Create a conclusion
`honcho conclusion delete <id>`	Delete a conclusion

Dreams (Representation History)

Command	Description
`honcho dream list`	Dreams in the workspace, newest first (`-p` for dreams about one peer, `--observer` for one representation)
`honcho dream inspect <id>`	What one dream changed: conclusions created (with what each was derived from), conclusions removed, and the peer card before and after

Config

Command	Description
`honcho config`	Show current config (API key redacted)

Agent Usage

All commands output JSON when stdout isn't a TTY, or when --json is forced. Collection commands emit JSON arrays, and single-resource commands emit JSON objects:

honcho peer list --json
honcho workspace inspect --json | jq '.peers'
honcho doctor --json              # machine-parseable health checklist

Errors are structured:

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

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

Agent skill

honcho-cli ships with a skill that teaches agents the right commands and conventions for inspecting and debugging a Honcho deployment. Install it anywhere skills are accepted (Claude Code, other skill-aware agents):

npx skills add plastic-labs/honcho

The picker lists every skill for Honcho — select honcho-cli .

Environment Variables

All HONCHO_* env vars work at runtime — no config file required.

Precedence (highest first): flag → env var → config file → default.

Variable	Flag	Description
`HONCHO_API_KEY`	`--api-key` (init)	Admin JWT
`HONCHO_BASE_URL`	`--base-url` (init)	API URL
`HONCHO_WORKSPACE_ID`	`-w` / `--workspace`	Workspace scope
`HONCHO_PEER_ID`	`-p` / `--peer`	Peer scope
`HONCHO_SESSION_ID`	`-s` / `--session`	Session scope
`HONCHO_JSON`	`--json`	Force JSON output (`1` / `true`)
`HONCHO_NO_UPDATE_CHECK`	—	Disable the once-a-day upgrade notice (`1` / `true`)
`HONCHO_PROFILE`	`--profile` (start/stop/status)	Local stack profile (default: `local`)
`HONCHO_FROM_URL` / `HONCHO_FROM_API_KEY`	`--from-url` (workspace replay); the key has no flag	Source instance, when it is not the configured one
`HONCHO_TO_URL` / `HONCHO_TO_API_KEY`	`--to-url` (workspace replay); the key has no flag	Destination instance, when it is not the configured one
`LLM_OPENAI_API_KEY`	—	Provider key for `honcho start` (also `LLM_ANTHROPIC_API_KEY`, `LLM_GEMINI_API_KEY`)

# 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

Configuration

The CLI shares ~/.honcho/config.json with sibling Honcho tools. It owns two top-level keys: apiKey and environmentUrl (the full Honcho API URL, e.g. https://api.honcho.dev or http://localhost:8000). Everything else at the top level — hosts, sessions, saveMessages, sessionStrategy, etc. — is left untouched.

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

workspace_id / peer_id / session_id are per-command only — never persisted to the config file.

Development

Install from source in editable mode so changes are picked up live:

git clone https://github.com/plastic-labs/honcho
cd honcho
uv tool install --force --editable --from ./honcho-cli honcho-cli

Re-run any time — changes to honcho-cli/src/ are reflected immediately without reinstalling.

License

MIT

Navigation Menu

Repository navigation

honcho-cli

honcho-cli

README.md

honcho-cli

Install

Quick Start

Local stack

Commands

Onboarding

Workspaces

Peers

Sessions

Scopes

Messages

Conclusions (observations)

Dreams (Representation History)

Config

Agent Usage

Agent skill

Environment Variables

Configuration

Development

License

FilesExpand file tree

honcho-cli

Directory actions

More options

Directory actions

More options

Latest commit

History

honcho-cli

Folders and files

parent directory

README.md

honcho-cli

Install

Quick Start

Local stack

Commands

Onboarding

Workspaces

Peers

Sessions

Scopes

Messages

Conclusions (observations)

Dreams (Representation History)

Config

Agent Usage

Agent skill

Environment Variables

Configuration

Development

License