honcho-cli 0.1.0__tar.gz

honcho_cli-0.1.0/.gitignore

@@ -0,0 +1,195 @@
+.worktrees/
+api/**/*.db
+api/data
+api/docker-compose.yml
+
+*.db
+data
+redis-data
+docker-compose.yml
+compose.yml
+
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+*.sqlite
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+**/docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.backup*
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.DS_Store
+
+supabase/
+
+docs/node_modules
+
+timing_logs.csv
+
+config.json
+config.toml
+.aider*
+
+CRUSH.md
+.crush/
+
+metrics.jsonl
+AGENTS.md
+lancedb_data/
+grafana-data/

honcho_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,211 @@
+```
+██╗  ██╗ ██████╗ ███╗   ██╗ ██████╗██╗  ██╗ ██████╗
+██║  ██║██╔═══██╗████╗  ██║██╔════╝██║  ██║██╔═══██╗
+███████║██║   ██║██╔██╗ ██║██║     ███████║██║   ██║
+██╔══██║██║   ██║██║╚██╗██║██║     ██╔══██║██║   ██║
+██║  ██║╚██████╔╝██║ ╚████║╚██████╗██║  ██║╚██████╔╝
+╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝
+```
+
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "honcho-cli"
+version = "0.1.0"
+description = "A terminal for Honcho — memory that reasons."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Plastic Labs", email = "hello@plasticlabs.ai" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "typer>=0.15.0",
+    "honcho-ai>=2.0.0",
+    "rich>=13.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/plastic-labs/honcho"
+Repository = "https://github.com/plastic-labs/honcho"
+
+[project.scripts]
+honcho = "honcho_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/honcho_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-mock>=3.14.0",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

honcho_cli-0.1.0/src/honcho_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Honcho CLI — a terminal for Honcho."""
+
+__version__ = "0.1.0"