docs: updating with new CLI language
This commit is contained in:
ajspig
parent
311b21d153
commit
d0e0189961
|
|
@ -200,7 +200,9 @@ conventions, and is worth skimming even if you are not using an agent.
|
|||
|
||||
## Local setup
|
||||
|
||||
To **run** Honcho locally without developing the server, `uv tool install honcho-cli` then `honcho start` is enough — see [CLI in the README](./README.md#cli). For development of this repo, [Self-hosting in the README](./README.md#self-hosting) covers the Docker Compose path and a manual Postgres setup. Then:
|
||||
To run a personal instance, install the CLI (`uv tool install honcho-cli`) and then run `honcho start --setup` (Docker + an LLM provider key — not the Honcho API key from `honcho init`) — [CLI in the README](./README.md#cli).
|
||||
|
||||
To **develop this repo**, clone it and:
|
||||
|
||||
```bash
|
||||
uv sync # create the venv and install dependencies
|
||||
|
|
|
|||
17
README.md
17
README.md
|
|
@ -49,7 +49,8 @@ The Honcho project is split between several repositories, with this one hosting
|
|||
| -------------------------------------- | ---------------------------------------------------------- | ----------------------------- |
|
||||
| Give my coding agent persistent memory | Claude Code, OpenCode, OpenClaw, Hermes, or any MCP client | [Integrations](#integrations) |
|
||||
| Add memory to my product | Python or TypeScript SDK | [Quickstart](#quickstart) |
|
||||
| Run Honcho locally, or inspect one | `honcho start` / `honcho-cli` | [CLI](#cli) |
|
||||
| Run Honcho locally | Install CLI, then `honcho start --setup` | [CLI](#cli) |
|
||||
| Inspect a deployment | `honcho workspace inspect`, `honcho doctor` | [CLI](#cli) |
|
||||
| Self-host from source | Docker Compose or local development | [Self-hosting](#self-hosting) |
|
||||
|
||||
## Why Honcho
|
||||
|
|
@ -73,7 +74,7 @@ Concretely: workspaces hold peers, peers participate in sessions, messages live
|
|||
|
||||
## Quickstart
|
||||
|
||||
Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or run a local stack with [`honcho start`](#cli) and point the SDK at `http://localhost:8000`.
|
||||
Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or install the CLI and run [`honcho start --setup`](#cli), then point the SDK at `http://localhost:8000`.
|
||||
|
||||
### Python
|
||||
|
||||
|
|
@ -247,16 +248,18 @@ honcho doctor # verify config + connectivity
|
|||
honcho # banner + command list
|
||||
```
|
||||
|
||||
`uv tool install` only puts `honcho` on your PATH. `honcho init` / `honcho doctor` store a **Honcho** API key (or browser login) so the CLI can call the server. That is not the LLM provider key a local stack needs — `honcho start --setup` (Docker + provider key) is below.
|
||||
|
||||
`honcho init` shares `~/.honcho/config.json` with plugins and other Honcho tools. It owns `apiKey` and `environmentUrl` at the top level; everything else (`hosts`, `sessions`, …) is left untouched. On managed servers that advertise the device grant, init can log you in via the browser instead of pasting a key. Workspace / peer / session scope is per-command (`-w` / `-p` / `-s` or `HONCHO_*` env vars) — never persisted as CLI defaults.
|
||||
|
||||
### Local stack (no clone)
|
||||
|
||||
`honcho start` is the fastest way to run Honcho on your machine. It pulls the published image (`ghcr.io/plastic-labs/honcho:latest`), **pins that digest**, and brings up API + deriver + Postgres + Redis in Docker. You do not need to clone this repo. Inference stays cloud-side: pass `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` (or run `--setup`).
|
||||
`honcho start --setup basic` is the fastest way to run Honcho on your machine. It prompts for an LLM provider and API key (OpenAI, Anthropic, Gemini, or OpenAI-compatible), writes those into the profile `.env`, pulls `ghcr.io/plastic-labs/honcho:latest`, **pins that digest**, and brings up API + deriver + Postgres + Redis in Docker. You do not need to clone this repo. `honcho init` cannot replace this step — its `apiKey` is for calling a Honcho server, not for the deriver's LLM calls.
|
||||
|
||||
```bash
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
honcho start --setup basic # interactive provider + chat model
|
||||
honcho start --setup basic # interactive provider + chat model (writes LLM keys)
|
||||
honcho start --setup advanced # embeddings, deriver/dialectic models, dreams, flush
|
||||
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
|
||||
|
|
@ -332,7 +335,7 @@ Honcho's evals span LongMemEval, LoCoMo, and other long-conversation benchmarks.
|
|||
|
||||
## Self-hosting
|
||||
|
||||
Honcho is open source under AGPL-3.0. To **run** a personal instance, prefer [`honcho start`](#cli) — no clone, published GHCR image, Docker. The paths below are for building from source, contributing, or deploying without the CLI.
|
||||
Honcho is open source under AGPL-3.0. To **run** a personal instance, install the CLI (`uv tool install honcho-cli`) and then [`honcho start --setup`](#cli). The paths below are for building from source, contributing, or deploying without the CLI.
|
||||
|
||||
### Quick start (from source, Docker)
|
||||
|
||||
|
|
@ -692,7 +695,7 @@ For low-latency use cases, Honcho provides access to a `representation` endpoint
|
|||
- **TypeScript** — [`@honcho-ai/sdk`](https://www.npmjs.com/package/@honcho-ai/sdk) on npm · source in [`sdks/typescript/`](./sdks/typescript)
|
||||
- **CLI** — [`honcho-cli`](https://pypi.org/project/honcho-cli/) on PyPI · source in [`honcho-cli/`](./honcho-cli) · [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli)
|
||||
|
||||
SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version. The CLI is versioned on its own (`honcho-cli` 0.1.3+ includes `honcho start`).
|
||||
SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version. The CLI is versioned on its own (`honcho-cli` 0.1.4+ includes `honcho start`).
|
||||
|
||||
See the [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) for full API surface, the [API Reference](https://honcho.dev/docs/v3/api-reference/introduction) for the raw HTTP API, and per-SDK example folders for runnable demos.
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ one.
|
|||
|
||||
Test against an instance you operate. Do not run security testing against `api.honcho.dev`
|
||||
or against any Honcho deployment that is not yours — self-hosting is a first-class path and
|
||||
takes a few minutes to set up — `uv tool install honcho-cli && honcho start`, or see [Self-hosting](./README.md#self-hosting).
|
||||
takes a few minutes to set up — install the CLI (`uv tool install honcho-cli`) then run `honcho start --setup` (Docker + an LLM provider key), or see [Self-hosting](./README.md#self-hosting).
|
||||
|
||||
## What to Expect
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ This guide helps you match the right SDK version to your Honcho API version. New
|
|||
```
|
||||
</Card>
|
||||
<Card title="CLI" icon="terminal">
|
||||
**Latest:** v0.1.3
|
||||
**Latest:** v0.1.4
|
||||
|
||||
```bash
|
||||
uv tool install honcho-cli
|
||||
|
|
@ -32,8 +32,6 @@ This guide helps you match the right SDK version to your Honcho API version. New
|
|||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
CLI 0.1.3+ can start a local stack (`honcho start`) from `ghcr.io/plastic-labs/honcho:latest`. It talks to any v3 API — managed, self-hosted, or that local stack.
|
||||
|
||||
## Version Compatibility Table
|
||||
|
||||
| Honcho API Version | TypeScript SDK | Python SDK |
|
||||
|
|
|
|||
|
|
@ -189,10 +189,10 @@ conventions, and is worth skimming even if you are not using an agent.
|
|||
|
||||
## Local setup
|
||||
|
||||
To **run** Honcho locally without developing the server, `uv tool install honcho-cli`
|
||||
then `honcho start` is enough — see the [CLI reference](/v3/documentation/reference/cli).
|
||||
For development of this repo, [Self-hosting](/v3/contributing/self-hosting) covers
|
||||
the Docker Compose path and a manual Postgres setup. Then:
|
||||
To run a personal instance, install the CLI (`uv tool install honcho-cli`) and then run
|
||||
`honcho start --setup` (Docker + an LLM provider key) — [CLI reference](/v3/documentation/reference/cli).
|
||||
|
||||
To **develop this repo**, clone it and:
|
||||
|
||||
```bash
|
||||
uv sync # create the venv and install dependencies
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ icon: 'computer'
|
|||
|
||||
This guide helps you set up a local environment to run Honcho for development, testing, or self-hosting.
|
||||
|
||||
**Just want a running instance?** Skip the clone — [`honcho start`](/v3/documentation/reference/cli#local-stack) pulls a published image and starts API, deriver, Postgres, and Redis. The rest of this page is for building from source, contributing, or deploying without the CLI.
|
||||
**Just want a running instance?** `uv tool install honcho-cli` only installs the `honcho` command. Then run [`honcho start --setup`](/v3/documentation/reference/cli#local-stack) (Docker + an LLM provider key) — that pulls a published image and starts API, deriver, Postgres, and Redis. The rest of this page is for building from source, contributing, or deploying without the CLI.
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -63,12 +63,11 @@ For recommended model tiers per feature, using multiple providers, or direct ven
|
|||
|
||||
## Personal local stack (CLI)
|
||||
|
||||
Recommended if you want Honcho running locally without cloning this repo or building an image.
|
||||
Recommended if you want Honcho running locally without cloning this repo or building an image. Install the CLI, then run the setup wizard:
|
||||
|
||||
```bash
|
||||
uv tool install honcho-cli
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
# or: honcho start --setup basic
|
||||
honcho start --setup basic # prompts for LLM provider + key, then starts Docker
|
||||
```
|
||||
|
||||
`honcho start` pulls `ghcr.io/plastic-labs/honcho:latest`, pins that digest, and starts API + deriver + Postgres + Redis. Stack files live under `~/.honcho/profiles/local/`. It does **not** rewrite `environmentUrl` in `~/.honcho/config.json` (that file is shared with plugins). Talk to the stack with `HONCHO_BASE_URL=http://127.0.0.1:8000`, or run `honcho init --base-url http://127.0.0.1:8000` to persist local as the CLI default.
|
||||
|
|
@ -333,7 +332,7 @@ const client = new Honcho({
|
|||
### Next Steps
|
||||
|
||||
- **Configure Honcho**: Visit the [Configuration Guide](./configuration) for model tiers, provider options, and tuning
|
||||
- **Use the CLI**: [`honcho start`](/v3/documentation/reference/cli#local-stack) for a no-clone local stack; inspect with `honcho workspace inspect` / `honcho doctor`
|
||||
- **Use the CLI**: install with `uv tool install honcho-cli`, then [`honcho start --setup`](/v3/documentation/reference/cli#local-stack) for a local stack; inspect with `honcho workspace inspect` / `honcho doctor`
|
||||
- **Explore the API**: Check out the [API Reference](../api-reference/introduction)
|
||||
- **Try the SDKs**: See our [guides](../guides) for examples
|
||||
- **Join the community**: [Discord](https://discord.gg/honcho)
|
||||
|
|
|
|||
|
|
@ -95,7 +95,7 @@ Welcome to Honcho. We're excited to have you at the frontier of AI with us 🫡.
|
|||
Build your first stateful agent in minutes
|
||||
</Card>
|
||||
<Card title="CLI" icon="terminal" href="/v3/documentation/reference/cli">
|
||||
Inspect a deployment or run a local stack with `honcho start`
|
||||
Inspect a deployment, or `honcho start --setup` a local stack
|
||||
</Card>
|
||||
<Card title="Architecture" icon="sitemap" href="/v3/documentation/core-concepts/architecture">
|
||||
Deep dive into how Honcho's primitives fit together
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Running the code below requires an API key. Create an account and get your API k
|
|||
|
||||
Every new tenant gets \$100.00 in free credits on sign up. The code below costs ~\$0.04 to run, so don't worry--still plenty of free credits for iterating.
|
||||
|
||||
To run against a local stack instead, `uv tool install honcho-cli && honcho start`, then pass `base_url="http://localhost:8000"` (Python) / `baseUrl: "http://localhost:8000"` (TypeScript). See the [CLI reference](/v3/documentation/reference/cli#local-stack).
|
||||
To run against a local stack instead, install the CLI (`uv tool install honcho-cli`) and then run `honcho start --setup` (Docker + an LLM provider key). See the [CLI reference](/v3/documentation/reference/cli#local-stack).
|
||||
</Note>
|
||||
|
||||
#### 1. Install the SDK
|
||||
|
|
|
|||
|
|
@ -74,12 +74,12 @@ Inspect and debug a running Honcho deployment from your terminal, or run a perso
|
|||
|
||||
```bash
|
||||
uv tool install honcho-cli
|
||||
honcho init # API key or browser login, plus server URL
|
||||
honcho doctor # verify connectivity
|
||||
honcho start # optional: local API + deriver + Postgres + Redis (Docker)
|
||||
honcho init # Honcho API key / browser login (talk *to* a server)
|
||||
honcho start --setup basic # local stack: LLM provider key + Docker
|
||||
honcho doctor # verify connectivity
|
||||
```
|
||||
|
||||
`honcho start` pulls the published GHCR image — no clone required. It does not rewrite `environmentUrl` in the shared config file; prefix commands with `HONCHO_BASE_URL=http://127.0.0.1:8000` to talk to local. Pass `--setup basic` for an interactive LLM wizard.
|
||||
`honcho start --setup` pulls the published GHCR image — no clone required. It does not rewrite `environmentUrl` in the shared config file; prefix commands with `HONCHO_BASE_URL=http://127.0.0.1:8000` to talk to local.
|
||||
|
||||
The CLI also ships an agent skill. Install it with `npx skills add plastic-labs/honcho` and pick `honcho-cli` from the list.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,18 +18,22 @@ 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 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
|
||||
honcho start # optional: local API + deriver + Postgres + Redis (Docker)
|
||||
honcho doctor # verify your config + connectivity
|
||||
honcho # show banner + command list
|
||||
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` is the fastest way to run Honcho on your machine. It does **not** require cloning the Honcho repo. The CLI pulls the published image (`ghcr.io/plastic-labs/honcho:latest`), **pins that digest** in `~/.honcho/profiles/<name>/profile.json`, and starts API + deriver + Postgres + Redis via Docker. It is not the managed service at `api.honcho.dev`. Deriver and dialectic call your cloud LLM provider (OpenAI, Anthropic, or Gemini) with a key you supply.
|
||||
`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 (the key `honcho init` stores cannot be reused here), writes them into the profile `.env`, pulls `ghcr.io/plastic-labs/honcho:latest`, **pins that digest**, and starts API + deriver + Postgres + Redis via Docker. It is not the managed service at `api.honcho.dev`.
|
||||
|
||||
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`).
|
||||
|
||||
|
|
@ -43,9 +47,9 @@ honcho init --base-url http://127.0.0.1:8000 # persist local as the CLI defaul
|
|||
```
|
||||
|
||||
```bash
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
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
|
||||
|
|
|
|||
|
|
@ -22,19 +22,19 @@ uv tool install honcho-cli
|
|||
## Quick Start
|
||||
|
||||
```bash
|
||||
honcho init # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
|
||||
honcho start # optional: local API + deriver + Postgres + Redis (Docker)
|
||||
honcho doctor # verify your config + connectivity
|
||||
honcho # show banner + command list
|
||||
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 # show banner + command list
|
||||
```
|
||||
|
||||
`honcho init` reads `apiKey` and `environmentUrl` from the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share). If both are present, it confirms them with you; if either is missing (or you decline), it prompts for the missing value(s) and writes them back. On managed servers that advertise the device grant, you can log in via the browser instead of pasting a key. Host-specific entries under `hosts` are left untouched.
|
||||
`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` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. You do **not** need to clone this repo. Inference is cloud-side: set `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` (env overrides `config.toml`). Stack files live under `~/.honcho/profiles/local/` and are not committed to a project.
|
||||
`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.
|
||||
|
||||
|
|
@ -49,7 +49,6 @@ 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
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
honcho start --setup basic
|
||||
honcho start --setup advanced
|
||||
honcho status
|
||||
|
|
@ -63,7 +62,7 @@ honcho stop --wipe # also delete volumes
|
|||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json`. Browser login on managed servers. |
|
||||
| `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). |
|
||||
|
|
|
|||
Loading…
Reference in New Issue