Metadata-Version: 2.5
Name: honcho-cli
Version: 0.4.0
Summary: A terminal for Honcho — memory that reasons.
Project-URL: Homepage, https://github.com/plastic-labs/honcho
Project-URL: Repository, https://github.com/plastic-labs/honcho
Author-email: Plastic Labs <hello@plasticlabs.ai>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: certifi>=2026.10.19
Requires-Dist: click>=8.0.0
Requires-Dist: honcho-ai>=2.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

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

# honcho-cli

A terminal for [Honcho](https://honcho.dev) — memory that reasons.

## Install

As a standalone tool (recommended):

```bash
uv tool install honcho-cli
```

## Quick Start

```bash
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:

```bash
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`.

```bash
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 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 |

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

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

Errors are structured:

```json
{
  "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:

```bash
# 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):

```bash
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`) |
| `LLM_OPENAI_API_KEY` | — | Provider key for `honcho start` (also `LLM_ANTHROPIC_API_KEY`, `LLM_GEMINI_API_KEY`) |

```bash
# 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.

```json
{
  "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:

```bash
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
