> ## Documentation Index > Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Complete command reference for the agtOS CLI tool The `agtos` CLI provides a text-based interface for managing the agtOS system. It communicates with the running server via the REST API on the health port (default 4102). ## Installation ```bash theme={null} # Run directly (no install needed) npx agtos # Or install globally npm install -g agtos agtos ``` ## Global Options | Flag | Description | | ----------------- | -------------------------------------------------------- | | `--help`, `-h` | Show help message | | `--version`, `-v` | Show version | | `--api-url ` | Override API base URL (default: `http://localhost:4102`) | ## Commands ### `agtos start` Start the agtOS server. Spawns the server as a child process, monitors startup, and reports when the health endpoint is ready. ```bash theme={null} agtos start agtos start --port 8080 ``` | Flag | Description | | ----------------- | --------------------------------------------------------------- | | `--port ` | Override the health/API port (default: 4102). Must be 1--65535. | On first run, the CLI checks for configuration in this order: 1. Encrypted credentials at `~/.agtos/credentials.json` 2. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) 3. `.env.local` in the current directory If none are found, it guides you to run `agtos setup` first. Before starting, the CLI checks for port conflicts on all three ports (3000, 4100, 4102) and reports which process holds a conflicting port. Startup progress is displayed in real-time with per-service status: ``` ✓ Health endpoint ✓ Voice pipeline ✓ MCP server ✓ Task scheduler ✓ API routes agtOS server is running! Dashboard: http://localhost:4102 Health: http://localhost:4102/health Voice WS: ws://localhost:3000/audio MCP: http://localhost:4100/mcp ``` Startup timeout: 30 seconds. The server process receives forwarded SIGINT/SIGTERM signals for graceful shutdown. ### `agtos setup` Interactive first-run configuration wizard. Checks prerequisites, prompts for API keys, validates credentials against the actual provider API, configures model slots, and stores encrypted credentials. ```bash theme={null} agtos setup ``` The wizard performs these steps: 1. **Node.js version check** -- requires 22+ (exits if older) 2. **Docker check** -- optional, shows running status 3. **Ollama check** -- optional, shows installed status 4. **Anthropic API key** -- prompts for `sk-ant-api03-...` key from [console.anthropic.com](https://console.anthropic.com). Validates against the Anthropic API. Offers retry on failure. Press Enter to skip. 5. **OpenAI API key** -- optional, prompts for `sk-...` key from [platform.openai.com](https://platform.openai.com). Validates against the OpenAI API. 6. **Model slot configuration** -- configures the chat slot (required) with provider and model selection, plus an optional reasoning slot for complex tasks. Providers: `claude`, `openai`, `ollama`. 7. **Encrypt and store** -- saves credentials to `~/.agtos/credentials.json` (AES-256-GCM encrypted) and slot configuration to `~/.agtos/config.json`. If plaintext API keys exist in `.env.local`, they are migrated to the encrypted store and removed. 8. **Summary** -- shows configuration status and next steps ### `agtos status` Display system health and service status. Fetches data from the health and system info API endpoints. ```bash theme={null} agtos status ``` Shows: * Overall system health (healthy/degraded) * Per-service status (Redis, STT, TTS, Ollama, Claude, MCP) * Uptime, Node.js version, memory usage * Port configuration ### `agtos chat` Interactive text chat with the agtOS agent. Uses the same agent reasoning loop as the voice pipeline. ```bash theme={null} agtos chat ``` The chat command verifies the server is reachable, then opens an interactive prompt that connects to `POST /api/chat`. Each message has a 30-second timeout. Session continuity is automatic — the server assigns a session ID on the first message and the CLI reuses it for subsequent messages. Responses show metadata: duration, reasoning steps (if > 1), and tool calls (if any). Errors don't exit the loop — you can retry or continue chatting. **In-chat commands:** | Command | Action | | ------------------ | ------------------------------------------ | | `/quit` or `/exit` | Exit chat | | `/help` | Show available commands | | `/session` | Show current session ID | | `/new` | Clear session and start a new conversation | ### `agtos schedule` Manage scheduled tasks. ```bash theme={null} # List all scheduled tasks agtos schedule list # Create a new scheduled task agtos schedule create ``` **Create examples:** ```bash theme={null} # Cron task — run every day at 7 AM agtos schedule create "morning-briefing" cron "0 7 * * *" briefing.morning # Interval — check every 5 minutes agtos schedule create "status-check" interval "300000" system.check ``` | Argument | Description | | ------------ | ------------------------------------------------------------------------------------------------ | | `name` | Human-readable task name | | `type` | Schedule type: `cron`, `once`, or `interval` (case-sensitive) | | `expression` | Cron expression (for `cron`), Unix ms timestamp (for `once`), or interval in ms (for `interval`) | | `topic` | Event bus topic to publish when the task fires | ### `agtos memory` Search and manage agent memory. ```bash theme={null} # Search memory agtos memory search "last conversation about weather" # Import memories from external AI tools (Claude, ChatGPT, etc.) agtos memory import # Trigger a memory health sweep on demand agtos memory maintain agtos memory maintain --verbose agtos memory maintain --user alice ``` The `search` subcommand queries the episodic and semantic memory system via `GET /api/memory/search`. Multi-word queries are supported — `agtos memory search foo bar baz` searches for `"foo bar baz"`. Returns up to 20 results with relevance scores. The `import` subcommand scans for available external AI tool memories and imports them. Supported sources: Claude Code, Cursor, Windsurf, Aider, and GitHub Copilot. The `maintain` subcommand triggers an on-demand memory lint sweep via `POST /api/memory/maintain`. It prints a summary (conclusions examined, contradictions, stale, orphans, redundant, pruned, decayed, dangling sources) and exits with one of four codes: | Exit code | Meaning | | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `0` | Sweep completed successfully (report printed) | | `1` | Request failed (network error, server error, parse error) | | `2` | Sweep deferred by ResourceGuard — transient, retry later when the system is idle (HTTP 503, `errorCode: RESOURCES_BUSY`) | | `3` | Memory profile manager is not connected — operator action required, e.g., Redis down (HTTP 503, `errorCode: PROFILE_DISCONNECTED`) | | Flag | Description | | ----------------- | ------------------------------------------------------------------- | | `--user ` | Target a specific user ID (defaults to the single-user `'default'`) | | `--verbose`, `-v` | Print the full issue list instead of just the summary | The sweep can take 30-60 seconds on large knowledge bases; the CLI allows up to 120 seconds before timing out. ### `agtos task` Run a background agent task. The task is processed through the same agent reasoning loop as chat, but designed for longer-running workloads (60-second timeout). Multi-word topics are supported. ```bash theme={null} agtos task "research current weather in San Francisco" agtos task "summarize recent conversations" ``` ### `agtos models` Manage sherpa-onnx ONNX model files for the local voice pipeline. This command operates directly on the local filesystem and does not require the server to be running. ```bash theme={null} # List all available models with download status agtos models list # Download the default model set (~460MB) agtos models download --default # Download a specific model agtos models download sensevoice-int8 # Show model details agtos models info moonshine-tiny-en-int8 # Remove a downloaded model (prompts for confirmation) agtos models remove sensevoice-int8 # Remove without confirmation prompt agtos models remove sensevoice-int8 --force ``` **Default model set** (5 models needed for a full local voice pipeline): * `silero-vad` -- Voice Activity Detection * `moonshine-tiny-en-int8` -- Fast English STT * `sensevoice-int8` -- Multilingual STT (zh, en, ja, ko) * `kokoro-int8-multi-v1` -- TTS (Kokoro) * `zipformer-streaming-en-20m` -- Streaming STT for real-time partial results Models are stored in `~/.agtos/models/` (configurable via `AGTOS_MODEL_DIR`). ### `agtos doctor` System health diagnostics. Checks all dependencies and reports pass/warn/fail status with actionable remediation hints. ```bash theme={null} agtos doctor ``` Each check reports one of three statuses: `✓` pass (green), `⚠` warn (yellow), or `✗` fail (red). **Checks performed:** | # | Check | Pass | Warn | Fail | | -- | --------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | -------------------------- | | 1 | **Node.js** | 22+ installed | -- | Version too old | | 2 | **Docker** | Running | Installed but not running / not found | -- | | 3 | **Redis** | Reachable (with RediSearch status) | -- | Not reachable | | 4 | **Ollama** | Installed and running | Installed but not running / not found | -- | | 5 | **Speech models** | All 5 downloaded | Some downloaded | None downloaded | | 6 | **Credential file** | `~/.agtos/credentials.json` exists, permissions 0o600, salt and secret files present | Missing salt or secret | File missing or unreadable | | 7 | **Plaintext key migration** | No residual keys in `.env.local` | Plaintext keys detected (run `agtos setup` to migrate) | -- | | 8 | **Anthropic credentials** | Key validates against API | Network issue | Invalid or missing | | 9 | **OpenAI credentials** | Key validates against API | Validation failed | -- (optional) | | 10 | **Network** | api.anthropic.com reachable | Unreachable | -- | | 11 | **Config file** | `~/.agtos/config.json` found and valid JSON | Not found (uses defaults) | Invalid JSON | | 12 | **Health endpoint** | Responding on port 4102 | HTTP non-200 | Not running | | 13 | **Voice port** | Active on port 3000 | Not active | -- | | 14 | **MCP port** | Active on port 4100 | Not active | -- | The doctor finishes with a **feature degradation summary** showing which features are available based on the check results: * **Text chat**: Requires AI provider credentials * **Voice**: Requires speech models + AI provider * **Scheduling**: Requires Redis * **Memory**: Requires Redis * **Local AI routing**: Requires Ollama ## Environment Variables | Variable | Default | Description | | --------------- | ----------------------- | ------------------------------------------------------ | | `AGTOS_API_URL` | `http://localhost:4102` | API base URL for CLI commands | | `HEALTH_PORT` | `4102` | Health server port (used to construct default API URL) | ## What's next Manage ESP32, browser, and CLI devices with per-device authentication. Common issues and solutions for setup, voice, memory, and connectivity.