CLI Reference

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

# Run directly (no install needed)
npx agtos <command>

# Or install globally
npm install -g agtos
agtos <command>

Global Options

Flag	Description
`--help`, `-h`	Show help message
`--version`, `-v`	Show version
`--api-url <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.

agtos start
agtos start --port 8080

Flag	Description
`--port <number>`	Override the health/API port (default: 4102). Must be 1—65535.

On first run, the CLI checks for configuration in this order:

Encrypted credentials at ~/.agtos/credentials.json
Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY)
.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.

agtos setup

The wizard performs these steps:

Node.js version check — requires 22+ (exits if older)
Docker check — optional, shows running status
Ollama check — optional, shows installed status
Anthropic API key — prompts for sk-ant-api03-... key from console.anthropic.com. Validates against the Anthropic API. Offers retry on failure. Press Enter to skip.
OpenAI API key — optional, prompts for sk-... key from platform.openai.com. Validates against the OpenAI API.
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.
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.
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.

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.

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.

# List all scheduled tasks
agtos schedule list

# Create a new scheduled task
agtos schedule create <name> <type> <expression> <topic>

Create examples:

# 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.

# 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 <id>`	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.

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.

# 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.

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)

CLI Reference

Installation

Global Options

Commands

`agtos start`

`agtos setup`

`agtos status`

`agtos chat`

`agtos schedule`

`agtos memory`

`agtos task`

`agtos models`

`agtos doctor`

Environment Variables

What’s next

Device Registry

Troubleshooting

Documentation Index

​Installation

​Global Options

​Commands

​agtos start

​agtos setup

​agtos status

​agtos chat

​agtos schedule

​agtos memory

​agtos task

​agtos models

​agtos doctor

​Environment Variables

​What’s next

Device Registry

Troubleshooting

Installation

Global Options

Commands

`agtos start`

`agtos setup`

`agtos status`

`agtos chat`

`agtos schedule`

`agtos memory`

`agtos task`

`agtos models`

`agtos doctor`

Environment Variables

What’s next