From eccc2dd84ab216395dee11f6e353fccfcef113e6 Mon Sep 17 00:00:00 2001 From: ajspig Date: Mon, 13 Apr 2026 09:49:15 -0400 Subject: [PATCH] chore: updating documentation --- honcho-cli/README.md | 204 ++++++++++++++++---- honcho-cli/src/honcho_cli/commands/setup.py | 4 +- 2 files changed, 166 insertions(+), 42 deletions(-) diff --git a/honcho-cli/README.md b/honcho-cli/README.md index 6dd375ee..972cb2af 100644 --- a/honcho-cli/README.md +++ b/honcho-cli/README.md @@ -1,50 +1,120 @@ -# honcho-cli +``` +██╗ ██╗ ██████╗ ███╗ ██╗ ██████╗██╗ ██╗ ██████╗ +██║ ██║██╔═══██╗████╗ ██║██╔════╝██║ ██║██╔═══██╗ +███████║██║ ██║██╔██╗ ██║██║ ███████║██║ ██║ +██╔══██║██║ ██║██║╚██╗██║██║ ██╔══██║██║ ██║ +██║ ██║╚██████╔╝██║ ╚████║╚██████╗██║ ██║╚██████╔╝ +╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝╚═╝ ╚═╝ ╚═════╝ +``` -Agent-first admin & debugging CLI for [Honcho](https://honcho.dev). +# honcho-ai-cli + +Agent-first admin & debugging CLI for [Honcho](https://honcho.dev) — memory that reasons. ## Install +As a standalone tool (recommended): + ```bash -pip install honcho-cli -# or -uv pip install honcho-cli +uv tool install honcho-ai-cli ``` +As an extra on the Honcho SDK (if you want both the SDK and the CLI in one project): + +```bash +uv add honcho-ai[cli] +# or +pip install honcho-ai[cli] +``` + +Either way, you'll get the `honcho` command on your PATH. + ## Quick Start ```bash -# Configure -honcho config init - -# Or set values directly -honcho config set base_url https://api.honcho.dev -honcho config set api_key -honcho config set workspace_id - -# Inspect -honcho workspace inspect -honcho peer list -honcho peer inspect -honcho session messages --last 20 - -# Peer management -honcho peer create -honcho peer create --observe-me --metadata '{"role": "user"}' -honcho peer get-metadata -honcho peer set-metadata --metadata '{"role": "user"}' -honcho peer representation -honcho peer representation --search-query "preferences" --max-conclusions 20 - -# Debug -honcho peer card -honcho conclusion search "topic" --observer -honcho workspace queue-status - -# Admin -honcho key generate --workspace my-ws --expires 30d -honcho workspace delete --yes +honcho init # interactive wizard: API key, workspace, default peer +honcho doctor # verify your config + connectivity +honcho # show banner + command list ``` +`honcho init` walks you through picking a workspace and default peer from your available choices, tests the connection, and writes config to `~/.honcho/config.toml`. + +## Commands + +### Onboarding + +| Command | Description | +|---------|-------------| +| `honcho init` | Interactive setup wizard (or `--yes` for non-interactive) | +| `honcho doctor` | Health check: config, connectivity, workspace, peer, queue | + +### Workspaces + +| Command | Description | +|---------|-------------| +| `honcho workspace list` | List accessible workspaces | +| `honcho workspace inspect` | Peers, sessions, config for a workspace | +| `honcho workspace search ` | Search messages across workspace | +| `honcho workspace queue-status` | Deriver queue processing status | +| `honcho workspace delete ` | Delete a workspace (`--dry-run` first) | + +### Peers + +| Command | Description | +|---------|-------------| +| `honcho peer list` | List peers in the workspace | +| `honcho peer create ` | Create or get a peer | +| `honcho peer inspect ` | Card, session count, recent conclusions | +| `honcho peer card ` | Raw peer card content | +| `honcho peer chat ` | Query the dialectic about a peer | +| `honcho peer representation ` | Formatted representation | +| `honcho peer search ` | Search a peer's messages | +| `honcho peer get-metadata ` / `set-metadata` | Metadata operations | + +### Sessions + +| Command | Description | +|---------|-------------| +| `honcho session list` | List sessions in the workspace | +| `honcho session inspect ` | Peers, message count, summaries, config | +| `honcho session messages ` | Recent messages | +| `honcho session context ` | What an agent would see | +| `honcho session summaries ` | Short + long summaries | +| `honcho session peers ` / `add-peers` / `remove-peers` | Peer management | +| `honcho session search ` | Search messages in a session | +| `honcho session representation ` | Peer representation in a session | +| `honcho session delete ` | Destructive; requires `--yes` | + +### Messages + +| Command | Description | +|---------|-------------| +| `honcho message list` | List messages in a session | +| `honcho message get ` | Get a single message | + +### Conclusions (observations) + +| Command | Description | +|---------|-------------| +| `honcho conclusion list` | List conclusions | +| `honcho conclusion search ` | Semantic search | +| `honcho conclusion create` | Create a conclusion | +| `honcho conclusion delete ` | Delete a conclusion | + +### Keys + +| Command | Description | +|---------|-------------| +| `honcho key generate` | Generate a scoped JWT (workspace/peer/session) | + +### Config & schema + +| Command | Description | +|---------|-------------| +| `honcho config show` | Show current config (API key redacted) | +| `honcho config set ` | Set a single config value | +| `honcho describe resource ` | Schema introspection from live server | + ## Agent Usage All commands output JSON when stdout isn't a TTY, or when `--json` is forced: @@ -52,6 +122,7 @@ All commands output JSON when stdout isn't a TTY, or when `--json` is forced: ```bash honcho peer list --json honcho workspace inspect --json | jq '.peers' +honcho doctor --json # machine-parseable health checklist ``` Errors are structured: @@ -66,26 +137,53 @@ Errors are structured: } ``` +Non-interactive onboarding: + +```bash +# Full flags +honcho init --yes --api-key $HONCHO_API_KEY --workspace my-ws --peer my-peer + +# Or rely on existing config / env vars to fill in missing values +HONCHO_API_KEY=xxx honcho init --yes --workspace my-ws + +# If config already exists, this just validates and exits 0 +honcho init --yes +``` + +Schema discovery for agents that need to build requests dynamically: + +```bash +honcho describe resource peer --json +honcho describe resource session --json +``` + ## Context Threading -Set defaults to avoid repeating IDs: +Set defaults once, then skip IDs on subsequent commands: ```bash honcho config set peer_id peer_abc123 -honcho peer inspect # uses default -honcho peer card # uses default -honcho peer inspect other_id # positional arg overrides +honcho peer inspect # uses default +honcho peer card # uses default +honcho peer inspect other_id # positional arg overrides +``` + +Or override per invocation: + +```bash +honcho --workspace prod --peer ajspig peer card ``` ## Environment Variables | Variable | Description | |----------|-------------| -| `HONCHO_BASE_URL` | API base URL | +| `HONCHO_BASE_URL` | API base URL (default `https://api.honcho.dev`) | | `HONCHO_API_KEY` | Admin JWT | | `HONCHO_WORKSPACE_ID` | Default workspace | | `HONCHO_PEER_ID` | Default peer | | `HONCHO_SESSION_ID` | Default session | +| `HONCHO_JSON` | Force JSON output (`1` / `true`) | ## Global Flags @@ -96,3 +194,29 @@ honcho peer inspect other_id # positional arg overrides | `--workspace` / `-w` | Override workspace ID | | `--peer` / `-p` | Override peer ID | | `--session` / `-s` | Override session ID | +| `--version` / `-V` | Show version | + +## Configuration + +Config lives at `~/.honcho/config.toml` with this precedence (highest first): + +1. CLI flags (`--workspace`, `--peer`, ...) +2. Environment variables (`HONCHO_*`) +3. Config file +4. Defaults + +## 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-ai-cli +``` + +Re-run any time — changes to `honcho-cli/src/` are reflected immediately without reinstalling. + +## License + +MIT diff --git a/honcho-cli/src/honcho_cli/commands/setup.py b/honcho-cli/src/honcho_cli/commands/setup.py index 47f2eea7..00111122 100644 --- a/honcho-cli/src/honcho_cli/commands/setup.py +++ b/honcho-cli/src/honcho_cli/commands/setup.py @@ -111,9 +111,9 @@ def init( return # --- Interactive wizard --- - banner_content = f"[bold #B6DAFD]{BANNER}[/bold #B6DAFD]\n\n The Memory Layer for AI Agents" + banner_content = f"[bold #B6DAFD]{BANNER}[/bold #B6DAFD]\n\n Memory that reasons" _console.print() - _console.print(Panel(banner_content, expand=False, subtitle=f"Python SDK · v{__version__}")) + _console.print(Panel(banner_content, expand=False, subtitle=f"Honcho CLI · v{__version__}")) _console.print() _console.print("[bold]Welcome! Let's set up your Honcho CLI.[/bold]\n")