---
title: 'CLI Reference'
description: 'Command-line interface for Honcho — inspect workspaces, peers, sessions, and memory from your terminal'
icon: 'terminal'
---

import CliCommands from "/snippets/cli-commands.mdx";

## Install

<CodeGroup>
```bash uv (recommended)
uv tool install honcho-cli
```

```bash uvx (ephemeral)
uvx honcho-cli
```
</CodeGroup>

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

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

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

```bash
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](/v3/contributing/self-hosting).

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

```json
{
  "apiKey": "hch-v3-...",
  "environmentUrl": "https://api.honcho.dev",
  "hosts": { "claude_code": { "...": "..." } }
}
```
<Info>
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.
</Info>

### Runtime overrides

Workspace, peer, and session targeting are **per-command only** — pass flags or
`HONCHO_*` env vars on every invocation.

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

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

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

<CliCommands />

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

<Steps>
  <Step title="Survey the workspace">
    ```bash
    honcho workspace inspect --json
    honcho peer list --json
    ```
  </Step>
  <Step title="Inspect a specific peer">
    ```bash
    honcho peer inspect <peer_id> --json
    honcho peer card <peer_id> --json
    ```
  </Step>
  <Step title="Review the peer's memory">
    ```bash
    honcho conclusion list --observer <peer_id> --json
    honcho conclusion search "topic" --observer <peer_id> --json
    ```
  </Step>
  <Step title="Debug a session">
    ```bash
    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
    ```
  </Step>
</Steps>

<Tip>
  `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.
</Tip>

### A peer isn't learning

If new messages aren't producing new conclusions, work down the diagnostic ladder.

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

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

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

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

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