0009. CLI Tool Design

Status: Proposed
Date:
Categories:
Technology

0009. CLI Tool Design

Date: 2025-08-03

Status

Proposed

Context

With Caxton as an application server (ADR-0006), users need a command-line interface for operational tasks, debugging, and development workflows. The CLI must be intuitive for developers who have never used Rust while providing power users with advanced capabilities.

The CLI serves multiple audiences:

  • Developers: Quick iteration during agent development
  • Operators: Production deployment and monitoring
  • Debuggers: Troubleshooting distributed agent interactions

Decision Drivers

  • Zero Rust requirement: Users should never see or know about Rust
  • Discoverability: Commands should be intuitive and self-documenting
  • Progressive disclosure: Simple tasks simple, complex tasks possible
  • Speed: Sub-second response for common operations
  • Integration: Work seamlessly with existing tools (kubectl, docker, etc.)

Decision

We will implement a noun-verb CLI structure with progressive disclosure:

1. Command Structure

Noun-Verb Pattern:

caxton <noun> <verb> [options]

# Examples:
caxton agent deploy processor.wasm
caxton agent list
caxton message send --to processor --type task
caxton server status

Rationale: Matches user mental models (kubectl, docker, git)

2. Core Commands

# Agent Management
caxton agent deploy <file>      # Deploy new agent
caxton agent list              # List running agents
caxton agent logs <id>         # Stream agent logs
caxton agent delete <id>       # Remove agent
caxton agent inspect <id>      # Detailed agent info

# Message Operations
caxton message send            # Send message to agent
caxton message trace <id>      # Trace message flow
caxton message stream          # Stream all messages

# Server Operations
caxton server status           # Health and metrics
caxton server config           # View/edit configuration
caxton server logs            # Server-level logs

# Development Workflow
caxton dev watch <file>        # Auto-reload on changes
caxton dev test <file>         # Test agent locally
caxton dev validate <file>     # Pre-deployment checks

3. Progressive Disclosure

Level 1 - Getting Started:

$ caxton
Caxton Multi-Agent Orchestration (v1.0.0)

Quick Start:
  caxton agent deploy my-agent.wasm    Deploy your first agent
  caxton agent list                    See running agents
  caxton help                          Get detailed help

Examples:
  caxton agent deploy processor.wasm --name my-processor
  caxton message send --to my-processor --type task --data '{"id": 123}'

Run 'caxton help <command>' for more information.

Level 2 - Common Tasks:

$ caxton agent deploy --help
Deploy a WebAssembly agent to the server

Usage: caxton agent deploy <file> [options]

Options:
  -n, --name <name>           Agent name (default: from file)
  -c, --capabilities <list>   Comma-separated capabilities
  -r, --replicas <count>      Number of instances (default: 1)
  --canary                    Use canary deployment
  --shadow                    Deploy as shadow for testing

Examples:
  # Simple deployment
  caxton agent deploy processor.wasm

  # Production deployment with canary
  caxton agent deploy processor.wasm --canary --name prod-processor

  # High-availability deployment
  caxton agent deploy processor.wasm --replicas 3

Level 3 - Power User:

$ caxton agent deploy processor.wasm \
  --strategy canary \
  --canary-stages "5:5m,25:10m,50:10m" \
  --rollback-on "error_rate>1%,p99>100ms" \
  --resource-limits "memory=100Mi,cpu=1000m" \
  --env-from secrets/prod.env \
  --trace

4. Output Formats

Human-Friendly Default:

$ caxton agent list
AGENT ID        NAME            STATUS    UPTIME    MESSAGES
proc-7f8d9      processor       Running   2h30m     45,231
calc-2a4e1      calculator      Running   1h15m     12,054
filter-9b3c2    filter          Failed    -         0

3 agents (2 running, 1 failed)

Machine-Readable Options:

# JSON output for scripting
$ caxton agent list --output json

# Wide output with more columns
$ caxton agent list --output wide

# Custom columns
$ caxton agent list --output custom-columns=NAME:.name,MEM:.resources.memory

5. Interactive Features

Auto-completion:

# Bash/Zsh completion
$ caxton agent delete proc<TAB>
proc-7f8d9  proc-2a4e1  proc-9b3c2

# Dynamic completion for agent names
$ caxton message send --to <TAB>
processor  calculator  filter

Interactive Mode:

$ caxton interactive
caxton> agent list
[agent list output]
caxton> message send --to processor
Message type: task
Message data (JSON): {"work": "process_order", "id": 123}
✓ Message sent (trace: 7f8d9a2b)
caxton> trace 7f8d9a2b
[shows message flow through agents]

6. Error Handling

Clear, Actionable Errors:

$ caxton agent deploy broken.wasm
✗ Deployment failed: Validation error

The WebAssembly module failed validation:
  - Missing required export: 'handle_message'
  - Memory limit exceeds maximum (requested: 500MB, max: 100MB)

To fix:
  1. Ensure your agent exports 'handle_message' function
  2. Reduce memory usage or request limit increase

Run 'caxton dev validate broken.wasm' for detailed analysis.

Suggestions for Common Mistakes:

$ caxton agents list
✗ Unknown command: 'agents'

Did you mean?
  caxton agent list

Run 'caxton help' to see all commands.

7. Development Workflow Integration

Watch Mode:

$ caxton dev watch processor.wasm
👁  Watching processor.wasm for changes...
✓ Initial deployment successful
⟳ File changed, redeploying...
✓ Validation passed
✓ Agent updated (0.3s)

Testing Workflow:

$ caxton dev test processor.wasm --scenario order-processing
Running test scenario: order-processing
  ✓ Agent initialized
  ✓ Received order message
  ✓ Sent confirmation
  ✓ State correctly updated

All tests passed! (4/4)
Coverage: 92% of message handlers

Consequences

Positive

  • Intuitive: Noun-verb structure matches user expectations
  • Discoverable: Help at every level guides users
  • Powerful: Advanced features available when needed
  • Fast: Built on gRPC client for sub-second operations
  • Scriptable: JSON output and proper exit codes
  • Integrated: Works with standard Unix tools

Negative

  • Binary size: ~10MB due to gRPC and CLI framework
  • Installation: Requires separate download/install
  • Learning curve: Many commands to learn
  • Maintenance: CLI must stay synchronized with API

Mitigation Strategies

Binary Size:

  • Provide lightweight “caxton-lite” for CI/CD
  • Web-based UI alternative for some users

Installation:

  • One-line installers for all platforms
  • Package managers: brew, apt, yum
  • Docker image with CLI included

Learning Curve:

  • Interactive tutorial: caxton tutorial
  • Command suggestions for mistakes
  • Extensive examples in help text
  • ADR-0006: Application Server Architecture - Established need for CLI
  • ADR-0007: Management API Design - CLI uses gRPC API
  • ADR-0008: Agent Deployment Model - CLI implements deployment strategies

References