![\"Agentspan\"](\"https://github.com/agentspan-ai/agentspan/raw/main/assets/logo-light.png#gh-light-mode-only\"){kind=logo}
\n ![\"Agentspan\"](\"https://github.com/agentspan-ai/agentspan/raw/main/assets/logo-dark.png#gh-dark-mode-only\"){kind=logo}
\n\n \n \n
\n ![\"npm\"](\"https://img.shields.io/npm/v/@agentspan-ai/agentspan?color=blue\")
![\"Stars\"](\"https://img.shields.io/github/stars/agentspan-ai/agentspan?style=social\")
![\"License\"](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
![\"Discord\"](\"https://img.shields.io/discord/1234567890?label=Discord&logo=discord&color=5865F2\")
\n Main Repo •\n Docs •\n Discord •\n Python SDK •\n Server\n
\n\n---\n\n# Agentspan CLI\n\nCommand-line interface for managing the Agentspan runtime — start servers, run agents, stream events, and approve human-in-the-loop tasks from the terminal.\n\n## Install\n\n### npm\n\n```bash\nnpm install -g @agentspan-ai/agentspan\n```\n\n### Shell script\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/agentspan-ai/agentspan/main/cli/install.sh | sh\n```\n\n### From source\n\n```bash\ncd cli\ngo build -o agentspan .\n```\n\n## Quickstart\n\n```bash\n# Check system dependencies\nagentspan doctor\n\n# Set your LLM provider API key\nexport OPENAI_API_KEY=sk-...\n\n# Start the runtime server (downloads automatically on first run)\nagentspan server start\n\n# Create an agent config\nagentspan agent init mybot\n\n# Run an agent\nagentspan agent run --config mybot.yaml \"What is the weather in NYC?\"\n```\n\n## Commands\n\n### `agentspan server` — Server Management\n\n```bash\n# Start the server (downloads latest JAR if needed)\nagentspan server start\n\n# Start a specific version on a custom port\nagentspan server start --version 0.1.0 --port 9090\n\n# Start with a default model\nagentspan server start --model openai/gpt-4o\n\n# Use a locally built JAR\nagentspan server start --local\n\n# Stop the server\nagentspan server stop\n\n# View server logs\nagentspan server logs\n\n# Follow logs in real-time\nagentspan server logs -f\n```\n\nThe server JAR is downloaded from GitHub releases and cached in `~/.agentspan/server/`. On each `server start`, the CLI checks for updates and re-downloads if a newer version is available.\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--port, -p` | Server port | `6767` |\n| `--model, -m` | Default LLM model | — |\n| `--version` | Specific server version | latest |\n| `--jar` | Path to local JAR file | — |\n| `--local` | Use locally built JAR from `server/build/libs/` | `false` |\n\n### `agentspan agent` — Agent Operations\n\n```bash\n# Create a new agent config file\nagentspan agent init mybot\nagentspan agent init mybot --model anthropic/claude-sonnet-4-20250514 --format json\n\n# Run an agent and stream output\nagentspan agent run --name mybot \"Hello, what can you do?\"\nagentspan agent run --config mybot.yaml \"Hello, what can you do?\"\nagentspan agent run --name mybot --no-stream \"Fire and forget\"\n\n# Continue a conversation\nagentspan agent run --name mybot --session sess-123 \"Follow up question\"\n\n# List all registered agents\nagentspan agent list\n\n# Get agent definition as JSON\nagentspan agent get mybot\nagentspan agent get mybot --version 2\n\n# Delete an agent\nagentspan agent delete mybot\nagentspan agent delete mybot --version 1\n\n# Compile agent config to agent definition (inspect only)\nagentspan agent compile mybot.yaml\n```\n\n### Execution Management\n\n```bash\n# Check execution status\nagentspan agent status