Decision: CLI Tool (abx)

Status: implemented Implemented: 2026-09-02

Problem

Users need command-line access to sandbox management for scripting, CI/CD, and interactive use.

Decision

cli/ package with Click + Rich: - Lazy subcommand loading for < 200ms startup time - Commands: create, list, info, kill, exec, connect, run, upload, download, deploy + config + template + mcp + sandbox (sub-command groups) - Output formats: --format table|json|quiet (table default for TTY, json for pipes) - Exit codes: 0 (success), 1 (general error), 3 (auth error), 4 (not found), 5 (timeout), 6 (quota) - Global options: --json, --quiet, --verbose, --no-color, --ci, --log-level, --timeout, --region

CLI entry point: abx (configured in pyproject.toml [project.scripts]).

API Design

abx <command> [options]

Top-level commands: create list info kill exec connect run upload download deploy
Sub-command groups: config  template  mcp  sandbox
Global options:     --json --quiet --verbose --no-color --ci --log-level --timeout --region

Implementation

• Entry point: src/agent_sandbox/cli/main.py (LazyGroup lazy-loads subcommands)
• Command modules: src/agent_sandbox/cli/commands/ (sandbox.py, template.py, deploy.py, config_cmd.py, mcp.py, etc.)
• Output formatting: src/agent_sandbox/cli/formatters.py, src/agent_sandbox/cli/output.py
• Tests: tests/test_cli/

Alternatives considered

• argparse — Less ergonomic, no built-in rich output
• typer — Additional dependency, less mature than Click
• Fire — Auto-generates CLI from functions, less control

Dependencies

• click>=8.0 for CLI framework
• rich>=13.0 for terminal output formatting
• api/* for sandbox operations

Test Strategy

• Click CliRunner tests for all commands
• Output format verification (table, json, quiet)
• Exit code verification for error scenarios

Acceptance criteria

• ✅ abx create → exec → kill flow works end-to-end
• ✅ Startup time < 200ms (lazy imports)
• ✅ All output formats work correctly