chore: updating documentation
This commit is contained in:
ajspig
parent
023e63e45c
commit
eccc2dd84a
|
|
@ -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 <your-admin-jwt>
|
||||
honcho config set workspace_id <your-workspace>
|
||||
|
||||
# Inspect
|
||||
honcho workspace inspect
|
||||
honcho peer list
|
||||
honcho peer inspect <peer_id>
|
||||
honcho session messages <session_id> --last 20
|
||||
|
||||
# Peer management
|
||||
honcho peer create <peer_id>
|
||||
honcho peer create <peer_id> --observe-me --metadata '{"role": "user"}'
|
||||
honcho peer get-metadata <peer_id>
|
||||
honcho peer set-metadata <peer_id> --metadata '{"role": "user"}'
|
||||
honcho peer representation <peer_id>
|
||||
honcho peer representation <peer_id> --search-query "preferences" --max-conclusions 20
|
||||
|
||||
# Debug
|
||||
honcho peer card <peer_id>
|
||||
honcho conclusion search "topic" --observer <peer_id>
|
||||
honcho workspace queue-status
|
||||
|
||||
# Admin
|
||||
honcho key generate --workspace my-ws --expires 30d
|
||||
honcho workspace delete <workspace_id> --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 <query>` | Search messages across workspace |
|
||||
| `honcho workspace queue-status` | Deriver queue processing status |
|
||||
| `honcho workspace delete <id>` | Delete a workspace (`--dry-run` first) |
|
||||
|
||||
### 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 <id> <query>` | Query the dialectic about a peer |
|
||||
| `honcho peer representation <id>` | Formatted representation |
|
||||
| `honcho peer search <id> <query>` | Search a peer's messages |
|
||||
| `honcho peer get-metadata <id>` / `set-metadata` | Metadata operations |
|
||||
|
||||
### Sessions
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `honcho session list` | List sessions in the workspace |
|
||||
| `honcho session inspect <id>` | Peers, message count, summaries, config |
|
||||
| `honcho session messages <id>` | Recent messages |
|
||||
| `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 delete <id>` | Destructive; requires `--yes` |
|
||||
|
||||
### Messages
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `honcho message list` | List messages in a session |
|
||||
| `honcho message get <id>` | Get a single message |
|
||||
|
||||
### Conclusions (observations)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `honcho conclusion list` | List conclusions |
|
||||
| `honcho conclusion search <query>` | Semantic search |
|
||||
| `honcho conclusion create` | Create a conclusion |
|
||||
| `honcho conclusion delete <id>` | 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 <key> <value>` | Set a single config value |
|
||||
| `honcho describe resource <name>` | 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
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
|
|
|
|||
Loading…
Reference in New Issue