CLI Commands

Global Options

agentzero [OPTIONS] <COMMAND>

Flag	Description
--data-dir <PATH>	Override data/config directory (alias: --config-dir)
--config <PATH>	Override config file path
-v, --verbose	Increase verbosity: -v=error, -vv=info, -vvv=debug, -vvvv=trace
--json	Emit structured JSON output for any command

Exit Codes

Code	Meaning
0	Success (including --help, --version)
1	Runtime or execution failure
2	CLI usage or argument parsing error

---

Core Commands

agent

Send a single message through the agent loop. The agent processes your message, calls tools as needed, and returns a response.

agentzero agent -m "hello"
agentzero agent -m "List files in the current directory"
agentzero agent -m "Summarize this repo" --provider openai --model gpt-4o-mini
agentzero agent -m "hello" --profile my-anthropic-profile

Flag	Description
-m, --message <TEXT>	(Required) Message to send
-p, --provider <NAME>	Override the configured provider (e.g., openrouter, openai, ollama)
--model <ID>	Override the configured model (e.g., gpt-4o-mini, llama3.1:8b)
--profile <NAME>	Use a specific auth profile by name (from auth list)

onboard

Generate a starter agentzero.toml config file in the current directory. The interactive wizard walks you through provider, model, memory, and security settings.

agentzero onboard                               # Quick setup (uses defaults or env vars)
agentzero onboard --interactive                  # Full wizard with prompts
agentzero onboard --force --provider openrouter --model anthropic/claude-sonnet-4-6 --yes

Flag	Description
--interactive	Launch full onboarding wizard
--force	Overwrite existing config without confirmation
--provider <NAME>	Provider name (openai, openrouter, anthropic, ollama, etc.)
--base-url <URL>	Provider base URL
--model <ID>	Model identifier
--memory <BACKEND>	Memory backend: sqlite (default), lucid, markdown, none
--memory-path <PATH>	Database file path
--allowed-root <PATH>	Filesystem scope root
--allowed-commands <LIST>	Comma-separated command allowlist
--api-key <KEY>	API key (quick mode only, ignored with --interactive)
--yes	Skip prompts, auto-accept defaults
--no-totp	Disable OTP in quick setup (not recommended)
--channels-only	Reconfigure channels only (fast repair)

status

Show a minimal runtime status summary including recent memory count.

agentzero status
agentzero --json status

doctor

Run diagnostics for model availability and trace inspection.

doctor models

Probe model catalogs across all configured providers. Shows provider status, model count, and cache freshness.

agentzero doctor models                          # Probe all known providers
agentzero doctor models --provider openrouter    # Specific provider only
agentzero doctor models --use-cache              # Prefer cached catalogs

Flag	Description
--provider <NAME>	Probe specific provider only
--use-cache	Prefer cached catalogs when available

doctor traces

List recent tool execution traces and model replies in reverse chronological order. Reads from {data_dir}/trace_events.jsonl.

agentzero doctor traces                          # Last 20 events
agentzero doctor traces --event tool --contains shell --limit 50
agentzero doctor traces --id abc123              # Show specific event

Flag	Description
--id <ID>	Show specific trace event by id
--event <TYPE>	Filter by event type
--contains <TEXT>	Case-insensitive text match across message/payload
--limit <N>	Maximum events to display (default: 20)

providers

List all supported AI providers with their status and configuration.

agentzero providers                              # Table output
agentzero providers --json                       # Machine-readable
agentzero providers --no-color                   # Disable ANSI colors

Flag	Description
--json	Emit machine-readable JSON output
--no-color	Disable ANSI color in table output

providers-quota

Inspect provider rate limits, API key status, and circuit breaker state.

agentzero providers-quota
agentzero providers-quota --provider openrouter --json

Flag	Description
--provider <NAME>	Specific provider to inspect
--json	Emit machine-readable JSON output

---

Gateway & Operations

gateway

Start the HTTP gateway server in the foreground. Blocks until stopped. Exposes REST, WebSocket, and webhook endpoints for programmatic access.

agentzero gateway                                # Defaults: 127.0.0.1:8080
agentzero gateway --host 0.0.0.0 --port 8081    # Custom bind address
agentzero gateway --new-pairing                  # Clear paired tokens, fresh pairing code

Flag	Description
--host <HOST>	Interface to bind (default: 127.0.0.1)
-p, --port <PORT>	Port to bind (default: 8080)
--new-pairing	Clear all paired tokens and generate a fresh pairing code

Endpoints:

Endpoint	Method	Description
/health	GET	Health check
/metrics	GET	Prometheus-style metrics
/pair	POST	Pair a client (get bearer token)
/api/chat	POST	Send a chat message
/v1/chat/completions	POST	OpenAI-compatible completions API
/v1/models	GET	List available models
/v1/ping	POST	Connectivity check
/v1/webhook/:channel	POST	Channel-specific webhook
/ws/chat	GET	WebSocket chat

daemon

Manage the background daemon process. The daemon runs the gateway server as a detached process with logging.

daemon start

Start the daemon. By default spawns a background process and returns immediately. Logs to {data_dir}/daemon.log.

agentzero daemon start                           # Background, default 127.0.0.1:8080
agentzero daemon start --port 9000               # Custom port
agentzero daemon start --foreground              # Foreground (for systemd/debugging)

Flag	Description
--host <HOST>	Interface to bind (default: 127.0.0.1)
-p, --port <PORT>	Port to bind (default: 8080)
--foreground	Run in foreground instead of daemonizing

daemon stop

Stop the running daemon process.

agentzero daemon stop

daemon status

Show whether the daemon is running, its PID, bind address, and log file location.

agentzero daemon status
agentzero daemon status --json

Flag	Description
--json	Emit JSON with running, host, port, pid, started_at_epoch_seconds

service

Install and manage AgentZero as an OS service for automatic startup on boot. Auto-detects systemd or OpenRC.

agentzero service install                        # Install service
agentzero service start                          # Start service
agentzero service stop                           # Stop service
agentzero service restart                        # Restart service
agentzero service status                         # Show install/running state
agentzero service uninstall                      # Remove service
agentzero service --service-init systemd install # Force systemd

Flag	Description
--service-init <INIT>	Init system: auto (default), systemd, openrc

dashboard

Launch an interactive terminal dashboard for real-time monitoring.

agentzero dashboard

---

Configuration

config

Inspect and modify the agentzero.toml configuration file.

config show

Print the effective configuration as JSON. Secrets are masked by default.

agentzero config show                            # Secrets masked
agentzero config show --raw                      # Secrets visible

Flag	Description
--raw	Emit raw JSON without masking secrets

config get

Query a single config value by dot-separated path.

agentzero config get provider.model
agentzero config get agent.max_tool_iterations

config set

Set a config value in agentzero.toml. Type is auto-inferred (bool, int, float, string).

agentzero config set provider.model "gpt-4o"
agentzero config set agent.max_tool_iterations 20

config schema

Print the config template or JSON schema.

agentzero config schema                          # TOML template
agentzero config schema --json                   # JSON schema

Flag	Description
--json	Emit JSON schema instead of TOML template

---

Authentication

auth

Manage provider authentication profiles. Supports OAuth (browser-based), API key paste, and multi-profile switching. Credentials are stored in an encrypted auth store at {data_dir}/auth/.

auth login

Start an interactive login flow. Opens a browser for OAuth providers (OpenAI Codex, Gemini) or prompts for an API key (Anthropic).

agentzero auth login                             # Interactive provider selection
agentzero auth login --provider openai-codex     # OAuth browser flow
agentzero auth login --provider gemini           # OAuth browser flow
agentzero auth login --provider anthropic        # API key paste

Flag	Description
--provider <NAME>	Provider: openai-codex, gemini, anthropic. Prompts if omitted
--profile <NAME>	Profile name to save under (default: default)
--device-code	Use OAuth device-code flow (planned)

auth setup-token

Save an API key or token for a provider. Prompts interactively if --token is omitted.

agentzero auth setup-token --provider openrouter
agentzero auth setup-token --provider anthropic --token sk-ant-...
agentzero auth setup-token --provider openai --token sk-... --profile work

Flag	Description
--provider <NAME>	(Required) Provider id
--token <TOKEN>	Token value. Prompts interactively if omitted
--profile <NAME>	Profile name (default: default)
--activate	Set as active profile after saving (default: true)

auth paste-token

Alias for setup-token. Same flags and behavior.

auth paste-redirect

Complete an OAuth flow by pasting the redirect URL or authorization code.

agentzero auth paste-redirect --provider openai-codex
agentzero auth paste-redirect --provider gemini --input "https://..."

Flag	Description
--provider <NAME>	(Required) Provider id
--profile <NAME>	Profile name (default: default)
--input <URL_OR_CODE>	Redirect URL or raw auth code. Prompts if omitted

auth refresh

Refresh an expired OAuth access token using a stored refresh token.

agentzero auth refresh --provider openai-codex
agentzero auth refresh --provider gemini --profile work

Flag	Description
--provider <NAME>	(Required) Provider id
--profile <NAME>	Profile name to refresh

auth use

Set the active auth profile for a provider. The active profile is used when no --profile override is given.

agentzero auth use --provider anthropic --profile work

Flag	Description
--provider <NAME>	(Required) Provider id
--profile <NAME>	(Required) Profile name or full profile id

auth list

Show all configured auth profiles.

agentzero auth list
agentzero auth list --json

Flag	Description
--json	JSON array with name, provider, active, has_refresh_token, timestamps

auth status

Show the active profile, token type, and expiry information for each provider.

agentzero auth status
agentzero auth status --json

Flag	Description
--json	JSON with active_profile, active_provider, total_profiles, expiry info

auth logout

Remove an authentication profile.

agentzero auth logout --provider openrouter
agentzero auth logout --provider anthropic --profile work

Flag	Description
--provider <NAME>	(Required) Provider id
--profile <NAME>	Profile name (default: default)

---

Built-in Tools

The agent has access to built-in tools that it calls automatically during the agent loop. Tools are gated by the [security] section in agentzero.toml. There is no CLI command to invoke tools directly — they are used by the agent when processing messages.

Always Available

Tool	Description
read_file	Read files within the configured allowed_root
shell	Execute shell commands (restricted to allowed_commands)
glob_search	Find files by glob pattern
content_search	Search file contents by text or regex
memory_store	Persist a key-value memory entry
memory_recall	Retrieve stored memory entries
memory_forget	Delete memory entries
image_info	Read image metadata (dimensions, format, EXIF)
docx_read	Extract text from Microsoft Word documents
pdf_read	Extract text from PDF files
screenshot	Capture a screenshot
task_plan	Create and manage structured task plans
process_tool	Manage system processes
subagent_spawn	Start a sub-agent with a specific task
subagent_list	List active sub-agents
subagent_manage	Stop or manage sub-agent lifecycle
cli_discovery	Check if shell commands exist on PATH, get runtime info
proxy_config	Configure proxy settings
delegate_coordination_status	Track delegation status across agents
sop_list	List available standard operating procedures
sop_status	Show status of an active SOP
sop_advance	Advance to the next step in an SOP
sop_approve	Approve the current SOP step
sop_execute	Execute an SOP

Conditionally Available

These tools are disabled by default and must be enabled in agentzero.toml:

Tool	Config Flag	Description
write_file	security.write_file.enabled = true	Write files within allowed root
apply_patch	security.write_file.enabled = true	Apply unified diffs to files
file_edit	security.write_file.enabled = true	Make targeted edits to files
git_operations	security.enable_git = true	Run git commands
cron_add	security.enable_cron = true	Add a scheduled task
cron_list	security.enable_cron = true	List scheduled tasks
cron_remove	security.enable_cron = true	Remove a scheduled task
cron_update	security.enable_cron = true	Update a scheduled task
cron_pause	security.enable_cron = true	Pause a scheduled task
cron_resume	security.enable_cron = true	Resume a paused task
web_search	web_search.enabled = true	Search the web (DuckDuckGo, Brave, Jina)
browser	browser.enabled = true	Browse web pages
browser_open	browser.enabled = true	Open a URL in the browser
mcp_tool	security.mcp.enabled = true	Call MCP (Model Context Protocol) servers
process_plugin	security.plugin.enabled = true	Execute process-based plugins
composio	composio.enabled = true	Use Composio integrations
pushover	security.enable_pushover = true	Send push notifications via Pushover
model_routing_config	Automatically enabled when model router is configured	Configure model routing rules
delegate	Automatically enabled when delegate agents are configured in [agents.*]	Delegate tasks to other agents

Tool Security Configuration

[security]
allowed_root = "."                         # File access boundary
allowed_commands = ["ls", "pwd", "cat"]    # Shell command allowlist

[security.read_file]
max_read_bytes = 262144                    # 256 KiB default
allow_binary = false

[security.write_file]
enabled = false                            # Disabled by default
max_write_bytes = 65536                    # 64 KiB limit

[security.shell]
max_args = 32
max_arg_length = 4096
max_output_bytes = 65536
forbidden_chars = ";&|><$`\n\r"

[security.mcp]
enabled = false
allowed_servers = []

[security.url_access]
block_private_ip = true
allow_loopback = false

[security.otp]
enabled = false
gated_actions = ["shell", "file_write", "browser_open", "browser", "memory_forget"]

---

Skills

skill

Skills are composable agent behaviors written in TypeScript, Rust, Go, or Python. They are stored in an encrypted state file at {data_dir}/skills-state.json.

skill list

List all installed skills with their enabled status and source.

agentzero skill list
agentzero skill list --json

Flag	Description
--json	Emit JSON array of skill records

skill install

Install a skill by name and source.

agentzero skill install --name research --source local
agentzero skill install --name code-review --source builtin

Flag	Description
--name <NAME>	(Required) Skill name (alphanumeric, hyphens, underscores)
--source <SOURCE>	Source of the skill (default: local)

skill test

Run a basic validation check on an installed skill. Shows source and enabled status.

agentzero skill test --name research

Flag	Description
--name <NAME>	(Required) Skill name

skill remove

Remove an installed skill.

agentzero skill remove --name research

Flag	Description
--name <NAME>	(Required) Skill name

skill new

Scaffold a new skill project with a manifest and source file.

agentzero skill new my-skill                     # TypeScript (default)
agentzero skill new my-skill --template rust     # Rust
agentzero skill new my-skill --template python --dir ./skills

Flag	Description
name	(Required, positional) Name for the new skill
--template <LANG>	Scaffold template: typescript/ts (default), rust/rs, go, python/py
--dir <PATH>	Target directory (default: workspace root)

Generated files:

• skill.json — manifest with name, version, template, entry point
• src/main.{ts,rs,go,py} — scaffolded source file

skill audit

Audit an installed skill for security and compatibility. Checks manifest validity, source trust, and permission scope.

agentzero skill audit --name research
agentzero skill audit --name research --json

Flag	Description
--name <NAME>	(Required) Skill name
--json	Emit JSON with checks: manifest_valid, source_trusted, permissions_scoped

skill templates

List available scaffold templates with their entry points.

agentzero skill templates

---

Plugins

plugin

Plugins are sandboxed WebAssembly modules that extend AgentZero’s capabilities. They run in an isolated WASM runtime (wasmtime) with configurable resource limits.

plugin new

Scaffold a plugin manifest template.

agentzero plugin new --id my-plugin
agentzero plugin new --id my-plugin --version 1.0.0 --entrypoint main --force

Flag	Description
--id <ID>	(Required) Plugin identifier
--version <VER>	Plugin version (default: 0.1.0)
--entrypoint <NAME>	WASM entrypoint function (default: run)
--wasm-file <PATH>	WASM file reference (default: plugin.wasm)
--out-dir <DIR>	Output directory (default: current directory)
--force	Overwrite existing manifest

plugin validate

Validate a plugin manifest for correctness. Checks id, version, entrypoint, WASM file extension, SHA256 format, and API version compatibility.

agentzero plugin validate --manifest manifest.json

Flag	Description
--manifest <PATH>	(Required) Path to manifest.json

plugin test

Run plugin preflight checks and optional execution in a sandboxed environment. Test isolation: 5s timeout, 5MB module limit, 64MB memory, no network, no filesystem writes.

agentzero plugin test --manifest manifest.json --wasm plugin.wasm
agentzero plugin test --manifest manifest.json --wasm plugin.wasm --execute

Flag	Description
--manifest <PATH>	(Required) Path to manifest.json
--wasm <PATH>	(Required) Path to compiled .wasm module
--execute	Execute the entrypoint after preflight (default: preflight only)

plugin dev

Run a local development loop: validate, preflight, and optionally execute with deterministic fixtures.

agentzero plugin dev --manifest manifest.json --wasm plugin.wasm
agentzero plugin dev --manifest manifest.json --wasm plugin.wasm --iterations 5

Flag	Description
--manifest <PATH>	(Required) Path to manifest.json
--wasm <PATH>	(Required) Path to .wasm module
--iterations <N>	Number of loop iterations (default: 1)
--execute	Execute entrypoint in addition to preflight (default: true)

plugin package

Package a plugin into an installable tar archive. Computes SHA256 checksum and embeds it in the manifest.

agentzero plugin package --manifest manifest.json --wasm plugin.wasm --out my-plugin.tar

Flag	Description
--manifest <PATH>	(Required) Path to manifest.json
--wasm <PATH>	(Required) Path to .wasm module
--out <PATH>	(Required) Output archive path

plugin install

Install a packaged plugin archive. Verifies checksum integrity, then installs to {data_dir}/plugins/{id}/{version}/.

agentzero plugin install --package my-plugin.tar
agentzero plugin install --package my-plugin.tar --install-dir ./plugins

Flag	Description
--package <PATH>	(Required) Path to plugin archive (.tar)
--install-dir <DIR>	Installation directory (default: {data_dir}/plugins)

plugin list

List installed plugins with their version and install location.

agentzero plugin list
agentzero plugin list --json

Flag	Description
--json	Emit JSON with install_root and plugins array
--install-dir <DIR>	Installation directory (default: {data_dir}/plugins)

plugin remove

Remove an installed plugin. Can remove a specific version or all versions.

agentzero plugin remove --id my-plugin                    # All versions
agentzero plugin remove --id my-plugin --version 0.1.0    # Specific version

Flag	Description
--id <ID>	(Required) Plugin identifier
--version <VER>	Specific version to remove (default: all versions)
--install-dir <DIR>	Installation directory (default: {data_dir}/plugins)

Plugin Manifest Format

{
  "id": "my-plugin",
  "version": "0.1.0",
  "entrypoint": "run",
  "wasm_file": "plugin.wasm",
  "wasm_sha256": "a1b2c3...",
  "capabilities": ["tool.call"],
  "hooks": ["before_tool_call"],
  "min_runtime_api": 1,
  "max_runtime_api": 1,
  "allowed_host_calls": []
}

WASM Isolation Defaults

Limit	Default	Test/Dev
Max execution time	30s	5s
Max module size	5 MB	5 MB
Max memory	256 MB	64 MB
Network access	No	No
Filesystem writes	No	No

tools

Inspect registered tools, their descriptions, and JSON schemas. Useful for debugging which tools the agent has access to and verifying schema definitions.

tools list

List all registered tools.

agentzero tools list
agentzero tools list --with-schema
agentzero tools list --json

Flag	Description
--with-schema	Only show tools that have a JSON input schema defined
--json	Output as JSON array

tools info

Show details for a specific tool.

agentzero tools info read_file
agentzero tools info shell

Argument	Description
<NAME>	(Required) Tool name to inspect

tools schema

Print the JSON input schema for a specific tool.

agentzero tools schema read_file
agentzero tools schema shell --pretty

Argument / Flag	Description
<NAME>	(Required) Tool name
--pretty	Pretty-print the JSON schema

---

Memory & Knowledge

memory

Inspect and manage the agent’s conversation memory store. Backend is configured in agentzero.toml (sqlite, lucid, markdown, or none).

memory list

List memory entries with pagination.

agentzero memory list
agentzero memory list --limit 100 --offset 50
agentzero memory list --json

Flag	Description
--limit <N>	Maximum entries to return (default: 50)
--offset <N>	Pagination offset (default: 0)
--category <CAT>	Filter by category (reserved)
--session <SID>	Filter by session (reserved)
--json	Emit machine-readable JSON output

memory get

Retrieve a memory entry by key prefix. Returns the most recent match.

agentzero memory get --key "session-abc"
agentzero memory get --json                      # Most recent entry

Flag	Description
--key <KEY>	Key or prefix to match (most recent if omitted)
--json	Emit machine-readable JSON output

memory stats

Show memory store statistics.

agentzero memory stats
agentzero memory stats --json

Flag	Description
--json	Emit machine-readable JSON output

memory clear

Delete memory entries. Can target specific keys or clear all.

agentzero memory clear --yes                     # Clear all (skip confirmation)
agentzero memory clear --key "old-session"       # Delete by key prefix

Flag	Description
--key <KEY>	Delete entries matching this key prefix
--category <CAT>	Filter by category (reserved)
--yes	Skip confirmation prompt
--json	Emit machine-readable JSON output

rag

Local retrieval-augmented generation index. Ingest documents and query them by semantic similarity. Requires the rag feature.

rag ingest

Add a document to the RAG index.

agentzero rag ingest --id doc1 --text "Important context about the project..."
agentzero rag ingest --id doc2 --file ./notes.md

Flag	Description
--id <ID>	(Required) Document identifier
--text <TEXT>	Inline text content
--file <PATH>	File path to ingest (alternative to --text)
--json	Emit machine-readable JSON output

rag query

Query the RAG index for relevant documents.

agentzero rag query --query "What was the decision?" --limit 5

Flag	Description
--query <TEXT>	(Required) Query text
--limit <N>	Maximum matches (default: 5)
--json	Emit machine-readable JSON output

---

Security & Safety

estop

Emergency stop — immediately halt agent execution at various severity levels. Can require OTP to resume.

agentzero estop                                  # Default: kill-all
agentzero estop --level kill-all --require-otp   # Require OTP to resume
agentzero estop --level network-kill             # Block all network access
agentzero estop --level domain-block --domain "*.example.com" --domain "evil.com"
agentzero estop --level tool-freeze --tool shell --tool write_file

Flag	Description
--level <LEVEL>	Severity: KillAll, NetworkKill, DomainBlock, ToolFreeze
--domain <PATTERN>	Domain pattern(s) for domain-block (repeatable)
--tool <NAME>	Tool name(s) for tool-freeze (repeatable)
--require-otp	Require TOTP code to resume

estop status

Show current emergency stop state, level, blocked domains/tools, and timestamp.

agentzero estop status

estop resume

Resume from emergency stop. Can resume partially (specific domains or tools) or fully.

agentzero estop resume                           # Resume all
agentzero estop resume --otp 123456              # Resume with OTP
agentzero estop resume --network                 # Resume network only
agentzero estop resume --domain "*.example.com"  # Unblock specific domain
agentzero estop resume --tool shell              # Unfreeze specific tool

Flag	Description
--network	Resume only network kill
--domain <PATTERN>	Unblock specific domain(s) (repeatable)
--tool <NAME>	Unfreeze specific tool(s) (repeatable)
--otp <CODE>	OTP code (prompted if required but omitted)

approval

Evaluate approval requirements for high-risk actions using the approval policy engine.

agentzero approval evaluate --actor agent --action shell --risk high
agentzero approval evaluate --actor agent --action shell --risk high --decision allow --approver admin --reason "deployment"

Flag	Description
--actor <NAME>	Actor requesting the action
--action <NAME>	Action being evaluated
--risk <LEVEL>	Risk level of the action
--approver <NAME>	Who approved the action
--decision <DECISION>	Decision: allow or deny
--reason <TEXT>	Reason for the decision
--json	Emit machine-readable JSON output

---

Models & Local Providers

models

Manage provider model catalogs. Models are cached with a 12-hour TTL.

models refresh

Fetch the latest model list from providers.

agentzero models refresh                         # Refresh configured provider
agentzero models refresh --all --force           # Force refresh all providers
agentzero models refresh --provider anthropic

Flag	Description
--provider <NAME>	Refresh specific provider (default: configured provider)
--all	Refresh all providers that support live discovery
--force	Force live refresh, ignore fresh cache

models list

List cached models for a provider.

agentzero models list
agentzero models list --provider ollama

Flag	Description
--provider <NAME>	List models for this provider (default: configured provider)

models set

Set the default model in your config file.

agentzero models set anthropic/claude-sonnet-4-6
agentzero models set gpt-4o-mini

models status

Show current provider, default model, and cache freshness.

agentzero models status

models pull

Download a model from a local provider (Ollama and similar). Shows a progress bar.

agentzero models pull llama3.1:8b
agentzero models pull llama3.1:8b --provider ollama

Flag	Description
--provider <NAME>	Provider to pull from (default: configured local provider)

local

Discover and manage local AI model services (Ollama, llama.cpp, LM Studio, vLLM, SGLang).

local discover

Scan default ports for running local AI services.

agentzero local discover
agentzero local discover --timeout-ms 5000 --json
agentzero local discover --retries 2    # Retry unreachable providers with backoff

Flag	Description
--timeout-ms <MS>	Probe timeout in milliseconds (default: 2000)
--retries <N>	Retry unreachable providers up to N times with backoff (default: 0)
--json	Emit machine-readable JSON output

local status

Show status of the configured local provider.

agentzero local status
agentzero local status --json

Flag	Description
--json	Emit machine-readable JSON output

local health

Run a health check against a specific local provider endpoint.

agentzero local health ollama
agentzero local health vllm --url http://gpu-server:8000

Flag	Description
provider	(Required, positional) Provider name: ollama, llamacpp, lmstudio, vllm, sglang
--url <URL>	Custom base URL (overrides default)

---

Scheduling & Hooks

cron

Manage scheduled tasks. Tasks are stored in {data_dir}/cron-tasks.json.

cron list

agentzero cron list
agentzero cron list --json

cron add

Add a scheduled task with a cron expression.

agentzero cron add --id backup --schedule "0 2 * * *" --command "agentzero agent -m 'run backup'"

Flag	Description
--id <ID>	(Required) Task identifier
--schedule <EXPR>	(Required) Cron expression
--command <CMD>	(Required) Command to execute

cron add-at

Add a task scheduled at a specific time.

agentzero cron add-at --id deploy --schedule "2026-03-15T10:00:00" --command "deploy.sh"

cron add-every

Add a recurring task with a cadence expression.

agentzero cron add-every --id heartbeat --schedule "5m" --command "agentzero status"

cron once

Add a one-time scheduled task.

agentzero cron once --id migrate --schedule "2026-03-01T00:00:00" --command "migrate"

cron update

Update an existing task’s schedule or command.

agentzero cron update --id backup --schedule "0 3 * * *"
agentzero cron update --id backup --command "new-backup-script"

Flag	Description
--id <ID>	(Required) Task identifier
--schedule <EXPR>	New schedule (optional)
--command <CMD>	New command (optional)

cron pause / cron resume / cron remove

agentzero cron pause --id backup
agentzero cron resume --id backup
agentzero cron remove --id backup

hooks

Manage lifecycle hooks that run at specific points in the agent execution cycle.

hooks list

agentzero hooks list
agentzero hooks list --json

hooks enable / hooks disable

agentzero hooks enable --name pre-tool
agentzero hooks disable --name pre-tool

hooks test

Run a hook test to verify it executes correctly.

agentzero hooks test --name pre-tool

---

Channels & Integrations

channel

Manage messaging channels (Telegram, Discord, Slack, etc.). Channel credentials are stored in an encrypted state file.

channel add

Add a new channel. Prompts for channel-specific configuration (API keys, chat IDs, etc.).

agentzero channel add                            # Interactive prompt
agentzero channel add telegram                   # Add by name
agentzero channel add discord

channel list

agentzero channel list

channel doctor

Run channel diagnostics — checks configured channels and dispatch engine.

agentzero channel doctor

channel start

Launch configured channels and test connectivity.

agentzero channel start

channel remove

agentzero channel remove                         # Interactive prompt
agentzero channel remove telegram                # Remove by name

integrations

Browse and validate available third-party integrations.

agentzero integrations list
agentzero integrations list --category ai --status enabled
agentzero integrations search --query "slack"
agentzero integrations info

Flag	Description
--category <CAT>	Filter by category
--status <STATUS>	Filter by status
--query <TEXT>	Search query

---

Templates

template

Manage template files that define agent behavior. Templates are Markdown files loaded at agent startup (e.g., AGENTS.md, IDENTITY.md, SOUL.md, TOOLS.md).

template list

List all template files with their status and source location.

agentzero template list
agentzero template list --json

Flag	Description
--json	JSON array with name, session, found, source

Available templates: AGENTS.md, BOOT.md, BOOTSTRAP.md, HEARTBEAT.md, IDENTITY.md, SOUL.md, TOOLS.md, USER.md

template show

Display the content of a specific template.

agentzero template show IDENTITY
agentzero template show soul                     # Case-insensitive

template init

Scaffold template files with default content.

agentzero template init                          # All templates
agentzero template init --name IDENTITY          # Single template
agentzero template init --dir ./templates --force

Flag	Description
--name <NAME>	Single template to scaffold (default: all)
--dir <DIR>	Target directory (default: workspace root)
--force	Overwrite existing files

template validate

Check that template files exist and have content.

agentzero template validate

---

Identity & Coordination

identity

Manage actor identities and roles. Identities track who (human, agent, service) is performing actions.

agentzero identity upsert --id agent-1 --name "Primary Agent" --kind agent
agentzero identity get --id agent-1
agentzero identity get --id agent-1 --json
agentzero identity add-role --id agent-1 --role admin

Subcommand	Description	Key Flags
upsert	Create or update an identity	--id, --name, --kind (Human/Agent/Service), --json
get	Show identity by id	--id, --json
add-role	Add a role to an identity	--id, --role, --json

coordination

Inspect and update the multi-agent coordination runtime.

agentzero coordination status
agentzero coordination status --json
agentzero coordination set --active-workers 4 --queued-tasks 10

Subcommand	Description	Key Flags
status	Show worker/task counts	--json
set	Update counts	--active-workers, --queued-tasks

cost

Track accumulated API usage cost.

agentzero cost status
agentzero cost status --json
agentzero cost record --tokens 1500 --usd 0.003
agentzero cost reset

Subcommand	Description	Key Flags
status	Show cost summary	--json
record	Record token usage	--tokens, --usd
reset	Reset cost summary	—

goals

Manage runtime goals for tracking agent progress.

agentzero goals list
agentzero goals list --json
agentzero goals add --id ship-v1 --title "Ship v1.0"
agentzero goals complete --id ship-v1

Subcommand	Description	Key Flags
list	List goals	--json
add	Add a goal	--id, --title
complete	Mark goal complete	--id

---

Utility

tunnel

Manage secure tunnels for exposing local services.

agentzero tunnel start --protocol https --remote example.com:443 --local-port 8443
agentzero tunnel start --name my-tunnel --protocol http --remote api.example.com:80 --local-port 3000
agentzero tunnel status
agentzero tunnel status --json
agentzero tunnel stop

Subcommand	Key Flags
start	--name (default: default), --protocol (http/https/ssh), --remote (host:port), --local-port
stop	--name
status	--name, --json

migrate

Migrate data from external runtimes.

agentzero migrate openclaw --source /path/to/openclaw
agentzero migrate openclaw --source /path/to/openclaw --dry-run

Flag	Description
--source <PATH>	Source directory to import from
--dry-run	Validate and preview without writing

update

Self-update operations. Check for new versions, apply updates, or roll back.

agentzero update --check                         # Quick check
agentzero update check --channel stable --json   # Detailed check
agentzero update apply --version 1.2.0           # Apply specific version
agentzero update rollback                        # Roll back to previous
agentzero update status                          # Show update state

Subcommand	Key Flags
check	--channel (default: stable), --json
apply	--version, --json
rollback	--json
status	--json

completions

Generate shell completion scripts. Pipe to your shell’s completion file.

agentzero completions --shell bash >> ~/.bashrc
agentzero completions --shell zsh >> ~/.zshrc
agentzero completions --shell fish > ~/.config/fish/completions/agentzero.fish

Flag	Description
--shell <SHELL>	Shell: bash, zsh, fish, elvish, powershell

hardware (feature-gated)

Discover hardware boards and inspect chip details. Requires the hardware feature.

agentzero hardware discover                      # Scan for boards
agentzero hardware info --chip STM32F401RETx     # Chip details
agentzero hardware introspect                    # Board introspection

peripheral (feature-gated)

Manage peripheral devices. Requires the hardware feature.

agentzero peripheral list
agentzero peripheral list --json
agentzero peripheral add --id sensor-1 --kind temperature --connection /dev/ttyUSB0
agentzero peripheral flash --id sensor-1 --firmware firmware.bin
agentzero peripheral flash-nucleo
agentzero peripheral setup-uno-q --host 192.168.0.48

Subcommand	Description	Key Flags
list	List registered peripherals	--json
add	Register a peripheral	--id, --kind, --connection, --json
flash	Flash firmware	--id, --firmware, --json
flash-nucleo	Flash Nucleo board profile	--json
setup-uno-q	Setup Uno Q	--host, --json