honcho-cli 0.1.0__py3-none-any.whl

honcho_cli/output.py

@@ -0,0 +1,104 @@
+"""Output formatting: JSON, tables, and structured errors.
+
+Detects TTY to auto-switch between human-readable and machine-parseable output.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console(stderr=True)
+stdout_console = Console()
+
+
+def is_tty() -> bool:
+    """Check if stdout is a TTY."""
+    return sys.stdout.isatty()
+
+
+# Global state for --json flag
+_force_json = False
+
+
+def set_json_mode(enabled: bool) -> None:
+    global _force_json
+    _force_json = enabled
+
+
+
+def use_json() -> bool:
+    """Should we output JSON?"""
+    return _force_json or os.environ.get("HONCHO_JSON", "").lower() in ("1", "true") or not is_tty()
+
+
+def print_json(data: Any) -> None:
+    """Print a single JSON value to stdout."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def print_table(columns: list[str], rows: list[list[str]], title: str | None = None) -> None:
+    """Print a rich table to stdout."""
+    table = Table(title=title, show_header=True, header_style="bold")
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*row)
+    stdout_console.print(table)
+
+
+def print_result(data: Any, columns: list[str] | None = None, title: str | None = None) -> None:
+    """Print data as JSON or table depending on mode.
+
+    For lists, uses JSON arrays in JSON mode or tables in TTY mode.
+    For dicts, uses JSON or key-value display.
+    """
+    if use_json():
+        print_json(data)
+    else:
+        if isinstance(data, list) and columns:
+            rows = []
+            for item in data:
+                row = [str(item.get(col, "")) if isinstance(item, dict) else str(item) for col in columns]
+                rows.append(row)
+            print_table(columns, rows, title=title)
+        elif isinstance(data, dict):
+            table = Table(show_header=False)
+            table.add_column("Field", style="bold")
+            table.add_column("Value")
+            for k, v in data.items():
+                val = json.dumps(v, default=str) if isinstance(v, (dict, list)) else str(v)
+                table.add_row(k, val)
+            stdout_console.print(table)
+        else:
+            stdout_console.print(data)
+
+
+def print_error(code: str, message: str, details: dict | None = None) -> None:
+    """Print structured error."""
+    err = {
+        "error": {
+            "code": code,
+            "message": message,
+        }
+    }
+    if details:
+        err["error"]["details"] = details
+
+    if use_json():
+        print(json.dumps(err, default=str), file=sys.stderr)
+    else:
+        console.print(f"[red]Error[/red] ({code}): {message}")
+        if details:
+            for k, v in details.items():
+                console.print(f"  {k}: {v}")
+
+
+def status(msg: str) -> None:
+    """Print a status message to stderr."""
+    console.print(f"[dim]{msg}[/dim]")

honcho_cli/skills/CONTEXT.md

@@ -0,0 +1,50 @@
+---
+name: honcho-cli
+version: 0.1.0
+description: A terminal for Honcho — memory that reasons.
+---
+
+# Honcho CLI — Agent Interface
+
+## Overview
+
+`honcho` is a CLI for administering and debugging Honcho workspaces. It wraps the Honcho Python SDK with agent-friendly defaults: JSON output, structured errors, input validation.
+
+## Output Modes
+
+- **TTY**: Human-readable tables (default when interactive)
+- **Piped/scripted**: JSON automatically
+- `--json`: Force JSON output
+
+## Exit Codes
+
+- 0: Success
+- 1: Client error (bad input, not found)
+- 2: Server error
+- 3: Auth error
+
+## Config
+
+Shared with other Honcho tools at `~/.honcho/config.json`. The CLI owns only
+`apiKey` and `environmentUrl` at the top level. Host-specific
+entries under `hosts` are untouched.
+
+Run `honcho init` to confirm or set those two values. Workspace / peer /
+session are per-command — pass them via flags or env vars:
+
+```bash
+honcho peer card -w my-workspace -p my-peer
+# or
+export HONCHO_WORKSPACE_ID=my-workspace
+export HONCHO_PEER_ID=my-peer
+honcho peer card
+```
+
+## Command Groups
+
+- `honcho config` — Manage CLI configuration
+- `honcho workspace` — Inspect, delete, search workspaces
+- `honcho peer` — Inspect, card, chat, search peers
+- `honcho session` — Inspect, messages, context, summaries
+- `honcho message` — List and get messages
+- `honcho conclusion` — List, search, create, delete conclusions

honcho_cli/skills/honcho-debug.md

@@ -0,0 +1,54 @@
+---
+name: honcho-cli-debug
+version: 0.1.0
+description: Debug Honcho peer representations and memory
+---
+
+# Honcho CLI — Debug Skills
+
+## Rules
+
+- Check queue status when derivation seems stalled
+- Compare peer card with conclusions to understand memory state
+
+## Debugging Memory Issues
+
+### Peer not learning?
+
+```bash
+# Check if observation is enabled
+honcho peer inspect <peer_id> --json | jq '.configuration'
+
+# Check queue — are messages being processed?
+honcho workspace queue-status --json
+
+# Check what conclusions exist
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "expected topic" --observer <peer_id> --json
+```
+
+### Session context looks wrong?
+
+```bash
+# See raw context
+honcho session context <session_id> --json
+
+# Check summaries
+honcho session summaries <session_id> --json
+
+# Check message history
+honcho message list <session_id> --last 50 --json
+```
+
+### Dialectic giving bad answers?
+
+```bash
+# Check what the peer card says
+honcho peer card <peer_id> --json
+
+# Check conclusions for the specific topic
+honcho conclusion search "topic" --observer <peer_id> --json
+
+# Try the dialectic directly
+honcho peer chat <peer_id> "what do you know about X?" --json
+```

honcho_cli/skills/honcho-inspect.md

@@ -0,0 +1,53 @@
+---
+name: honcho-cli-inspect
+version: 0.1.0
+description: Inspect Honcho workspace state for debugging
+---
+
+# Honcho CLI — Inspection Skills
+
+## Rules
+
+- Always use `--json` when processing output programmatically
+- Run `honcho peer inspect` before `honcho peer chat` to understand context
+- Use `honcho session context` to see exactly what an agent receives
+- Never run `honcho workspace delete` without `honcho workspace inspect` first
+
+## Inspection Workflow
+
+### 1. Understand the workspace
+
+```bash
+honcho workspace inspect --json
+```
+
+### 2. Find the peer
+
+```bash
+honcho peer list --json
+honcho peer inspect <peer_id> --json
+```
+
+### 3. Check peer's memory
+
+```bash
+honcho peer card <peer_id> --json
+honcho conclusion list --observer <peer_id> --json
+honcho conclusion search "topic" --observer <peer_id> --json
+```
+
+### 4. Debug a session
+
+```bash
+honcho session inspect <session_id> --json
+honcho message list <session_id> --last 20 --json
+honcho session context <session_id> --json
+honcho session summaries <session_id> --json
+```
+
+### 5. Search across workspace
+
+```bash
+honcho workspace search "query" --json
+honcho peer search <peer_id> "query" --json
+```

honcho_cli/validation.py

@@ -0,0 +1,44 @@
+"""Input hardening: validate resource IDs and workspace names.
+
+Agents hallucinate bad IDs. Catch them early with clear errors.
+"""
+
+from __future__ import annotations
+
+import re
+
+from honcho_cli.output import print_error
+
+UNSAFE_CHARS = re.compile(r'[?#%\x00-\x1f\x7f/\\]')
+
+
+def validate_resource_id(value: str, resource_type: str = "resource") -> str:
+    """Validate a resource ID. Returns the value if valid, raises SystemExit on invalid."""
+    if not value:
+        _fail(
+            "EMPTY_ID",
+            f"Empty {resource_type} ID provided",
+            {resource_type: ""},
+        )
+
+    if UNSAFE_CHARS.search(value):
+        _fail(
+            "INVALID_ID",
+            f"Invalid {resource_type} ID: contains unsafe characters (?, #, %, control chars, path separators)",
+            {resource_type: value},
+        )
+
+    if ".." in value:
+        _fail(
+            "INVALID_ID",
+            f"Invalid {resource_type} ID: contains path traversal",
+            {resource_type: value},
+        )
+
+    return value
+
+
+def _fail(code: str, message: str, details: dict) -> None:
+    """Print structured error and exit."""
+    print_error(code, message, details)
+    raise SystemExit(1)

honcho_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: honcho-cli
+Version: 0.1.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: honcho-ai>=2.0.0
+Requires-Dist: httpx>=0.27.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
+```
+
+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
+honcho init        # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
+honcho doctor      # verify your 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. Host-specific entries under `hosts` are left untouched.
+
+Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars — not persisted as CLI defaults.
+
+## Commands
+
+### Onboarding
+
+| Command | Description |
+|---------|-------------|
+| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json` |
+| `honcho doctor` | Health check: config, connectivity, workspace, peer, queue |
+
+### 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 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`) |
+| `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 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` |
+
+### 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
+```
+
+## 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`) |
+
+```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

honcho_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+honcho_cli/__init__.py,sha256=wl_8azVLKxDN05LO2VbP-deTdH4kflJ1NY_IVHF7RTM,67
+honcho_cli/_help.py,sha256=gurEYhfe-fMG1NledPOw-AR77xHRC4eDh_GGqXb9LlQ,5372
+honcho_cli/branding.py,sha256=wFFE7xPsAoVoCJcOFmBPNgvLnRtDyzNRrzzadfYSmRA,1049
+honcho_cli/common.py,sha256=mTTJ8Gk5lXewf_CCQImMpyGXSu5y4-c4u0SnY9Bxpfs,3819
+honcho_cli/config.py,sha256=PmaPZ79bRZybBL1as2X3vNBtpamB7xMiWgSFoM-vsys,4979
+honcho_cli/main.py,sha256=76t134BNhfMgRcKCyMeB_uKoW-URitAcTblyM61OJfA,2694
+honcho_cli/output.py,sha256=dn5TTLHx4Exdc14_JFm5Xjb8xMs2O3a7E3MsoM74kdk,2941
+honcho_cli/validation.py,sha256=IPP04h87SG8zRjFkKbEqHPJpmO9Bw_966bljcqlJz58,1197
+honcho_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+honcho_cli/commands/conclusion.py,sha256=xTcGoH54peav8AL2RB10sGA8niHVAsFS7reHzR16rHc,8486
+honcho_cli/commands/config_cmd.py,sha256=-GHiKyaoZQdDdCCsY2c2jo4NXWRbT5u-nwXbEYBG6AM,1012
+honcho_cli/commands/message.py,sha256=H3JZ3zOZi-kghk45J6xR6rxjuGHFm59H7Ltm_sfEtM0,6373
+honcho_cli/commands/peer.py,sha256=sS71oAW2bNHbyOIxvE8_zYxdcgMQkY_L-9CEXYC85ao,12458
+honcho_cli/commands/session.py,sha256=yLzUfPa9dyeIfX3d2g2TCaXh-bd1pTBK_Kk1HNRgJGw,16274
+honcho_cli/commands/setup.py,sha256=6TgAcJDIbRdmE3s_MXlptYUe7c97dsMETSr5Lq0jRcE,10516
+honcho_cli/commands/workspace.py,sha256=1Ei94ByZR0Csere0t0D8mFp0eSOpL9qCNa0myq4S1R8,11834
+honcho_cli/skills/CONTEXT.md,sha256=vmhJh122nmnX5R1S6PGwQDRnu22JUvq3J116DcqPoxU,1407
+honcho_cli/skills/honcho-debug.md,sha256=xtuvARv-SKN38mecV4Ha_Ab-oBlRN6xwzRWKXHRJT4A,1216
+honcho_cli/skills/honcho-inspect.md,sha256=_Ep8IoKlJthgoQVIj9kvIMkx2LA8KML61JKHabB9Ksk,1170
+honcho_cli-0.1.0.dist-info/METADATA,sha256=DirStT4aIg1PWpLGL-78hCRNAj_y4Z_NpnMYUC7tuFU,8680
+honcho_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+honcho_cli-0.1.0.dist-info/entry_points.txt,sha256=w1ZA8lLpsVY-roy0KtdgQ1wt8pvPgLGsmVq1KxNriHw,47
+honcho_cli-0.1.0.dist-info/RECORD,,

honcho_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

honcho_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+honcho = honcho_cli.main:app