Plastic Labs Internal Wiki

Recently Updated

cli.v1

9 min read

Honcho CLI Specification

Status: Draft Author: [TBD] Last Updated: 2025-01-13

1. Overview

1.1 Target Audience

Primary (Now): Honcho core contributors and developers working on the Honcho codebase itself.

Secondary (Future): Open source developers using Honcho who want to self-host their own instance.

The CLI should be designed with the primary audience in mind, but architected in a way that naturally extends to the self-hosting use case.

1.2 Problem Statement

Local development of Honcho currently requires:

  • Cloning the repository
  • Running uv sync to install dependencies
  • Manually starting the FastAPI server with uv run fastapi dev src/main.py
  • Separately running the deriver with uv run python -m src.deriver
  • Managing configuration via .env and config.toml
  • Setting up PostgreSQL (typically via Docker)

This creates friction for both Honcho contributors and developers building applications on top of Honcho.

1.3 Proposed Solution

Create a honcho CLI that can be:

  1. Installed globally via uv tool install honcho (or pip install honcho)
  2. Run from any directory with sensible defaults
  3. Used to manage all Honcho components (server, deriver, database, etc.)

1.3 Design Principles

  1. Convention over configuration: Sensible defaults that “just work”
  2. Progressive disclosure: Simple commands for common cases, flags for advanced use
  3. Transparency: Clear feedback about what’s running and where
  4. Composability: Each command should be independently useful

2. Command Reference

2.1 Core Commands

honcho serve

Start the Honcho API server.

# Basic usage - starts server with default settings
honcho serve
 
# Development mode with auto-reload
honcho serve --reload
 
# Specify host/port
honcho serve --host 0.0.0.0 --port 8080
 
# Run in Docker container
honcho serve --docker
 
# Production mode with workers
honcho serve --workers 4

Behavior:

  • Starts uvicorn with the FastAPI application
  • Uses configuration from (in order of precedence):
    1. CLI flags
    2. Environment variables
    3. Local .honcho/config.toml or honcho.toml
    4. Global ~/.honcho/config.toml
    5. Built-in defaults

Open Questions:

  • Should --reload be the default (dev-first) or explicit?
  • Should it auto-start postgres if not available?

honcho deriver

Start the deriver background worker.

# Start a single deriver instance
honcho deriver
 
# Start multiple workers
honcho deriver --workers 3
 
# Run specific task types only
honcho deriver --tasks representation,summary

Behavior:

  • Connects to the same database as serve
  • Processes queued tasks (representation, summary, dream)
  • Can run alongside or separately from the server

Open Questions:

  • Should honcho serve --with-deriver be a convenience flag?
  • How to handle graceful shutdown?

honcho init

Initialize a new Honcho project or configure the CLI.

# Interactive setup
honcho init
 
# Initialize with defaults
honcho init --defaults
 
# Initialize for Docker-based setup
honcho init --docker

Behavior:

  • Creates .honcho/ directory with:
    • config.toml - local configuration
    • data/ - local database files (if using SQLite)
    • logs/ - log files
  • Optionally creates docker-compose.yml for full stack

honcho status

Show the current state of Honcho services.

honcho status

Example Output:

Honcho Status
─────────────────────────────────────
Server:     Running (http://localhost:8000)
Deriver:    Running (2 workers)
Database:   Connected (PostgreSQL 15.2)
Queue:      47 pending tasks

Configuration:
  Config:   .honcho/config.toml
  Data:     .honcho/data/
  Logs:     .honcho/logs/

2.2 Utility Commands

honcho openapi

Output the OpenAPI specification.

# Print to stdout
honcho openapi
 
# Write to file
honcho openapi > openapi.json
 
# Specific format
honcho openapi --format yaml

honcho docs

Launch the API documentation.

# Open docs in browser (starts server if needed)
honcho docs
 
# Just print the URL
honcho docs --url-only

honcho nuke

Clean up local state (destructive).

# Interactive confirmation
honcho nuke
 
# Skip confirmation
honcho nuke --force
 
# Nuke specific things
honcho nuke --db        # Database only
honcho nuke --logs      # Logs only
honcho nuke --all       # Everything including config

Behavior:

  • Removes .honcho/data/ contents
  • Optionally removes logs
  • Never removes config without --all
  • Requires confirmation unless --force

honcho doctor

Diagnose issues with the local setup.

honcho doctor

Example Output:

Honcho Doctor
─────────────────────────────────────
[✓] Python version: 3.11.5
[✓] honcho version: 0.1.0
[✓] Configuration found: .honcho/config.toml
[✗] Database: Connection failed
    → PostgreSQL not running. Run: docker compose up -d postgres
[✓] Required environment variables set
[!] Optional: OPENAI_API_KEY not set (needed for default LLM)

honcho bench

Run the test bench for evaluating Honcho behavior.

# Run all benchmarks
honcho bench
 
# Run specific benchmark suite
honcho bench --suite memory
 
# Output results to file
honcho bench --output results.json

Open Questions:

  • What benchmarks should be included?
  • Should this require a running server or start its own?

2.3 Advanced Commands (Future)

honcho monitor

Launch a TUI dashboard for monitoring (uxie-style).

honcho monitor

honcho codegen

Generate SDK code from the OpenAPI spec.

# Generate TypeScript SDK
honcho codegen --lang typescript --output ./sdk
 
# Generate Python SDK
honcho codegen --lang python --output ./sdk

honcho mock

Run a mock server for SDK testing.

honcho mock --port 8001

3. Configuration

3.1 Configuration Hierarchy

Configuration is resolved in the following order (later overrides earlier):

  1. Built-in defaults - Sensible defaults for local development
  2. Global config - ~/.honcho/config.toml
  3. Local config - .honcho/config.toml or honcho.toml in current directory
  4. Environment variables - HONCHO_* prefix
  5. CLI flags - Explicit command-line arguments

3.2 Configuration File Format

# honcho.toml or .honcho/config.toml
 
[server]
host = "127.0.0.1"
port = 8000
reload = true
workers = 1
 
[database]
# SQLite for simple local dev
url = "sqlite+aiosqlite:///.honcho/data/honcho.db"
 
# Or PostgreSQL for full features
# url = "postgresql+psycopg://user:pass@localhost:5432/honcho"
 
[deriver]
workers = 2
batch_size = 10
 
[llm]
provider = "openai"
model = "gpt-4o-mini"
 
[llm.providers.openai]
api_key = "${OPENAI_API_KEY}"
 
[llm.providers.anthropic]
api_key = "${ANTHROPIC_API_KEY}"
 
[logging]
level = "INFO"
format = "pretty"  # or "json"

3.3 Environment Variables

All configuration can be overridden via environment variables:

HONCHO_SERVER_HOST=0.0.0.0
HONCHO_SERVER_PORT=8080
HONCHO_DATABASE_URL=postgresql://...
HONCHO_LLM_PROVIDER=anthropic
HONCHO_LOG_LEVEL=DEBUG

3.4 State Directories

DirectoryPurposeLocation
Global configUser-wide defaults~/.honcho/config.toml
Local configProject-specific config.honcho/config.toml
DataDatabase files, embeddings.honcho/data/
LogsApplication logs.honcho/logs/
CacheTemporary files.honcho/cache/

Open Questions:

  • Should we support XDG Base Directory spec on Linux?
  • How to handle Windows paths?

4. Architecture

4.1 Package Structure

honcho/
├── __init__.py
├── __main__.py          # Entry point: python -m honcho
├── cli/
│   ├── __init__.py
│   ├── main.py          # Click/Typer app definition
│   ├── commands/
│   │   ├── serve.py
│   │   ├── deriver.py
│   │   ├── init.py
│   │   ├── status.py
│   │   ├── nuke.py
│   │   ├── doctor.py
│   │   └── ...
│   └── utils/
│       ├── config.py    # Configuration loading
│       ├── docker.py    # Docker integration
│       └── output.py    # Rich console output
├── server/              # Existing FastAPI app (renamed from src/)
├── deriver/             # Existing deriver
└── ...

4.2 CLI Framework Choice

Options:

  1. Typer - Modern, type-hint based, good autocompletion
  2. Click - Battle-tested, Typer is built on it
  3. argparse - Standard library, no dependencies

Recommendation: Typer

  • Already used in FastAPI ecosystem
  • Great developer experience
  • Automatic help generation
  • Rich integration for beautiful output

4.3 Entry Points

# pyproject.toml
 
[project.scripts]
honcho = "honcho.cli.main:app"

This enables:

# After pip/uv install
honcho serve
 
# Or via module
python -m honcho serve

5. Docker Integration

5.1 --docker Flag Behavior

When --docker is passed to commands:

honcho serve --docker

Behavior:

  1. Check if Docker is available
  2. Build/pull the Honcho image if needed
  3. Start a container with appropriate mounts and port bindings
  4. Stream logs to the terminal

5.2 Docker Compose Integration

# Generate docker-compose.yml
honcho init --docker
 
# Start all services via compose
honcho up
 
# Stop all services
honcho down

Generated docker-compose.yml:

version: "3.8"
 
services:
  honcho:
    image: ghcr.io/plastic-labs/honcho:latest
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://honcho:honcho@postgres:5432/honcho
    depends_on:
      - postgres
    volumes:
      - ./.honcho/config.toml:/app/config.toml:ro
 
  deriver:
    image: ghcr.io/plastic-labs/honcho:latest
    command: deriver
    environment:
      - DATABASE_URL=postgresql://honcho:honcho@postgres:5432/honcho
    depends_on:
      - postgres
      - honcho
 
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_USER=honcho
      - POSTGRES_PASSWORD=honcho
      - POSTGRES_DB=honcho
    volumes:
      - ./.honcho/data/postgres:/var/lib/postgresql/data
    ports:
      - "5432:5432"

5.3 Open Questions

  • Should the CLI be included in the Docker image?
  • How to handle honcho serve --docker vs docker compose up?
  • Should we support Podman as well?

6. Development Workflow Examples

6.1 Quick Start (New User)

# Install honcho
uv tool install honcho
 
# Initialize in current directory
honcho init
 
# Start the server (uses SQLite by default)
honcho serve
 
# In another terminal, start the deriver
honcho deriver

6.2 Full Stack with Docker

# Install honcho
uv tool install honcho
 
# Initialize with Docker setup
honcho init --docker
 
# Start everything
honcho up
 
# Check status
honcho status
 
# View logs
honcho logs --follow
 
# Tear down
honcho down

6.3 Contributing to Honcho

# Clone and install in development mode
git clone https://github.com/plastic-labs/honcho
cd honcho
uv sync
 
# Run from source (uses pyproject.toml entry point)
uv run honcho serve --reload
 
# Or the traditional way still works
uv run fastapi dev src/main.py

7. Migration Path

7.1 Backwards Compatibility

The existing methods should continue to work:

  • uv run fastapi dev src/main.py - unchanged
  • uv run python -m src.deriver - unchanged
  • Docker compose - unchanged

The CLI is an additional interface, not a replacement.

7.2 Deprecation Timeline

  1. Phase 1: CLI released alongside existing methods
  2. Phase 2: Documentation updated to prefer CLI
  3. Phase 3: Consider deprecating raw commands (optional)

8. Open Questions Summary

Configuration

  • Global (~/.honcho/) vs local (.honcho/) default preference?
  • Support for honcho.toml in project root vs .honcho/config.toml?
  • XDG Base Directory spec compliance?

Execution Model

  • Should honcho serve auto-start the deriver?
  • Should honcho serve auto-start postgres?
  • Graceful shutdown handling?
  • Multi-process vs multi-threaded deriver workers?

Docker

  • CLI in Docker image or separate?
  • Support for --docker flag vs dedicated honcho up command?
  • Podman support?

Scope

  • Is this a dev tool only, or should it be production-ready?
  • Should it support custom dreams/consumers as plugins?
  • Mock server priority?
  • Built-in coding agent - what would this do?

Distribution

  • Package name on PyPI (is honcho available?)
  • Versioning strategy (sync with API version?)

9. Implementation Plan

Phase 1: Foundation

  • Set up CLI structure with Typer
  • Implement honcho serve (wrap existing FastAPI app)
  • Implement honcho deriver (wrap existing deriver)
  • Basic configuration loading

Phase 2: Developer Experience

  • Implement honcho init
  • Implement honcho status
  • Implement honcho doctor
  • Implement honcho nuke

Phase 3: Documentation & Distribution

  • Implement honcho openapi
  • Implement honcho docs
  • PyPI packaging
  • Documentation

Phase 4: Advanced Features

  • Docker integration (--docker flags)
  • honcho up / honcho down commands
  • honcho monitor TUI
  • honcho bench

Phase 5: Extensibility

  • Plugin system for custom commands
  • SDK codegen
  • Mock server

10. References

Appendix A: Command Comparison

CurrentProposed CLINotes
uv run fastapi dev src/main.pyhoncho serveSimpler
uv run fastapi dev src/main.py --reloadhoncho serve --reloadSame flags
uv run python -m src.deriverhoncho deriverSimpler
docker compose uphoncho upOptional wrapper
Manual config editinghoncho initGuided setup
Check processes manuallyhoncho statusUnified view

Appendix B: Similar Tools for Reference

  • FastAPI CLI - fastapi dev, fastapi run
  • Django - django-admin, manage.py
  • Rails - rails server, rails console
  • Hugo - hugo server, hugo new
  • Vite - vite dev, vite build

Graph View

Backlinks