Skip to main content
The AgentOS CLI (agentos) provides a comprehensive command-line interface for managing every aspect of your agent operating system. From spawning agents to configuring security policies, the CLI gives you complete control over your AgentOS deployment.

​
Installation

Install AgentOS with a single command: 
curl -fsSL https://raw.githubusercontent.com/iii-hq/agentos/main/scripts/install.sh | sh
This installs both iii-engine (dependency) and agentos binary to ~/.local/bin.

​
Installation Options

# Install a specific version
AGENTOS_VERSION=v0.1.0 curl -fsSL ... | sh

# Custom install directory
BIN_DIR=/usr/local/bin curl -fsSL ... | sh

​
Quick Start

Initialize and start AgentOS: 
# Initialize with quick setup
agentos init --quick

# Set your API key
agentos config set-key anthropic $ANTHROPIC_API_KEY

# Start the engine
agentos start

# Chat with the default agent
agentos chat default

​
Command Groups

The CLI is organized into logical command groups:

Agent Commands

Create, list, chat with, and manage agents

Workflow Commands

Create and execute multi-step workflows

Config Commands

Manage configuration and LLM models

Security Commands

Audit trails, approvals, vault, and session management

​
System Commands

​
init

Initialize AgentOS configuration and directories. 
agentos init [--quick]
​
--quick
boolean
Skip interactive prompts and use defaults
Creates the following directories in ~/.agentos/:
  • data/ - Runtime data storage
  • skills/ - Installed skills
  • agents/ - Agent definitions
  • logs/ - System logs
  • state/ - State storage

​
start

Start the AgentOS engine and all workers. 
agentos start
Starts services on:
  • Engine: ws://localhost:49134
  • HTTP API: http://localhost:3111
  • Streams: ws://localhost:3112
  • Metrics: http://localhost:9464

​
stop

Stop all AgentOS workers and the engine. 
agentos stop

​
status

Display system status including worker count and uptime. 
agentos status [--json]
​
--json
boolean
Output status in JSON format
Example output: 
● agentos v0.1.0
  Workers: 18
  Uptime:  3600s

​
health

Check system health. 
agentos health [--json]
​
--json
boolean
Output health check in JSON format

​
doctor

Diagnose system issues and optionally repair them. 
agentos doctor [--json] [--repair]
​
--json
boolean
Output diagnostics in JSON format
​
--repair
boolean
Attempt to repair detected issues
Checks:
  • Engine connectivity
  • Worker status
  • State directory integrity
  • Configuration validity

​
Interactive Commands

​
chat

Start an interactive chat session with an agent. 
agentos chat [agent]
​
agent
string
Agent ID to chat with (defaults to “default”)
Type exit or quit to end the session.

​
message

Send a single message to an agent. 
agentos message <agent> <text> [--json]
​
agent
string
required
Agent ID to message
​
text
string
required
Message text to send
​
--json
boolean
Output response in JSON format
Example: 
agentos message coder "Review the API changes in src/api.ts"

​
Utility Commands

​
tui

Launch the terminal UI dashboard (21 screens). 
agentos tui
Provides interactive screens for:
  • Dashboard, Agents, Chat, Channels, Skills
  • Hands, Workflows, Sessions, Approvals, Logs
  • Memory, Audit, Security, Peers, Extensions
  • Triggers, Templates, Usage, Settings, Wizard

​
dashboard

Open the web dashboard in your browser. 
agentos dashboard

​
logs

View or stream system logs. 
agentos logs [--lines N] [--follow]
​
--lines
number
default:"50"
Number of log lines to display
​
--follow
boolean
Stream logs in real-time (like tail -f)

​
completion

Generate shell completion scripts. 
agentos completion <shell>
​
shell
string
required
Shell type: bash, zsh, fish, or powershell
Example setup: 
# Bash
agentos completion bash > /etc/bash_completion.d/agentos

# Zsh
agentos completion zsh > ~/.zsh/completion/_agentos

# Fish
agentos completion fish > ~/.config/fish/completions/agentos.fish

​
onboard

Interactive onboarding wizard. 
agentos onboard [--quick]
​
--quick
boolean
Use defaults and skip interactive prompts
Walks you through:
  1. Directory setup
  2. API key configuration
  3. Default model selection
  4. Initial configuration

​
reset

Factory reset - clears all AgentOS state. 
agentos reset [--confirm]
​
--confirm
boolean
required
Required flag to confirm reset operation
This operation is irreversible. All agents, workflows, sessions, and configuration will be deleted.

​
mcp

Start MCP (Model Context Protocol) server mode. 
agentos mcp
Runs AgentOS as an MCP server, enabling integration with MCP-compatible tools.

​
Getting Help

Get help for any command: 
agentos --help
agentos agent --help
agentos config set --help

​
Environment Variables

​
AGENTOS_API_URL
string
default:"http://localhost:3111"
Override the default API base URL
​
ANTHROPIC_API_KEY
string
Anthropic API key for Claude models
​
OPENAI_API_KEY
string
OpenAI API key for GPT models

​
Next Steps

Agent Commands

Learn how to create and manage agents

Security Commands

Set up audit trails and security policies

Configuration

Configure API keys and model settings

Workflows

Create multi-step automated workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us