CLI Reference

az init

Initialize a new project.

az init [--private] [--editor <editor>]

Flag	Description
--private	Use private-by-default policy (network denied, local-only routing)
--editor	Generate editor/tool config. Values: vscode, cursor, zed, neovim, vim, claude, codex, gemini

The --editor flag generates integration files for the specified editor or CLI tool:

Editor/Tool	Generated Files
vscode	.vscode/tasks.json
cursor	.cursor/rules
zed	.zed/tasks.json
neovim / nvim	Prints setup instructions
vim	Prints setup instructions
claude / codex / gemini	.mcp.json (MCP server config)

az bootstrap

Detect your platform, probe for existing LLM backends, and generate initial configuration.

az bootstrap [OPTIONS]

Flag	Description
--non-interactive	Skip prompts (for CI/scripting)
--skip-model	Skip model download after backend install

Probes ports 11434 (Ollama), 8080 (llama.cpp), 8000 (vLLM) for running backends. Recommends the best backend per platform (OS/arch), offers to install it, and generates .agentzero/models.json.

az chat

Start an interactive chat session.

az chat [OPTIONS]

Flag	Description
--remote	Allow remote model calls (local-only by default)
-m, --model	Model name (default: llama3.2)
--stream	Stream tokens as they arrive
-p, --provider	Provider: ollama, llama-cpp, vllm, lm-studio, anthropic
--url	Custom server URL
--resume	Resume a previous session by ID
--no-encrypt	Disable encryption of audit and session files (encrypted by default)
-P, --print	Single-shot mode: send one message, print response, exit
--mode	Output format for -P mode: text (default), json (pretty), jsonl (compact)
--hibernate-after	Hibernate after N minutes of inactivity. Saves a full checkpoint and exits.
--compaction	Context compaction strategy: simple (default), code-aware, role-budget
--compaction-model	Use an LLM for compaction (e.g., llama3.2:1b). Generates real summaries instead of text truncation.
--branch	Branch from a tree node when resuming (requires --resume)

az mcp

Start the MCP server for editor integration. Requires the mcp feature flag.

# Build with MCP support
cargo build --features mcp

# Run the MCP server
az mcp

Reads JSON-RPC 2.0 from stdin, writes to stdout. Running az mcp without the feature compiled in prints a message recommending ACP (az serve) as the native protocol. See ADR 0014.

az serve

Start the ACP server. Runs the full agentic loop — LLM inference with tool calling, approval flow, and streaming notifications. Editors connect over stdio to get a complete coding agent, not just a tool server.

az serve

az run

Run an installed skill.

az run <name>

Routes by skill runtime declared in SKILL.md:

• WASM skills — creates a session, checks policy, builds a sandbox profile, and executes the .wasm module through the wasmtime engine. WASM is compiled in by default (disable with --no-default-features); requires wasm_execution = "allow" or "require_approval" in policy.yml.
• Host-supervised skills — runs the entrypoint script (default run.sh) on the host with ShellCommand capability check. Policy-gated and audited.
• Scanner skills (with patterns.toml) — runs the security scanner against the current directory.
• Instruction-only skills — displays the SKILL.md content.

az install

Install a skill from a local path, GitHub owner/repo, or git URL.

az install <source>

The source is auto-detected:

Format	Example	Action
owner/repo	auser/my-skill	Download latest GitHub release
GitHub URL	https://github.com/auser/my-skill	Download latest GitHub release
Git URL	https://gitlab.com/user/repo	Clone via git
Local path	/path/to/skill or ./my-skill	Copy directory

GitHub installs verify SHA-256 checksums from the release notes. All install methods update .agentzero/skills.lock.

az publish

Package and publish a skill to a GitHub release.

az publish [path] [OPTIONS]

Flag	Description
--repo	Target GitHub repository (owner/repo). Auto-detected from git remote if omitted.
--tag	Release tag (default: v<version> from SKILL.md)

Requires GITHUB_TOKEN environment variable. Creates a GitHub release, uploads the tarball, and includes the SHA-256 checksum in the release notes.

az doctor

System diagnostic. Reports crate status, project initialization, policy rules, skills, vault, sessions, providers, and WASM sandbox status (compiled-in, policy setting, WASM skill count).

az doctor

az export

Export a session to markdown, HTML, or JSON.

az export <session-id> [OPTIONS]

Flag	Description
--format	Output format: md (default), html, json
-o, --output	Output file path (default: stdout)

The HTML format is self-contained with inline CSS and role-colored messages. Loads from session JSON or checkpoint format.

az history

List past chat sessions.

az history [--usage]

Flag	Description
--usage	Show token usage (input/output) from checkpoint files

az usage

Show token usage and cost report for sessions.

az usage [OPTIONS]

Flag	Description
--session	Show usage for a specific session ID
--last	Show the last N sessions (default: 5)
--json	Output as JSON

Reads audit logs to produce per-session token usage reports with provider breakdown.

az connect

Configure AgentZero as an MCP server for an external CLI tool.

az connect <tool> [--dry-run]

Tool	Config file
claude	.mcp.json
codex	.mcp.json
gemini	.mcp.json

Safely merges the AgentZero MCP server entry into existing config (creates backup). Use --dry-run to preview without writing.

az policy status

Show active policy rules.

az policy status

az audit tail

Show recent audit events.

az audit tail [-c, --count N]

az audit summary

Show a human-readable summary of audit activity across sessions.

az audit summary [--json]

Flag	Description
--json	Output structured JSON instead of human-readable text

Reports total sessions, total events, denied actions, and redactions applied.

az index

Build and query a semantic document index. Requires the rag feature (cargo build --features rag).

az index build

az index build [OPTIONS]

Flag	Description
--path	Directory to index (default: current directory)
--model	Embedding model (default: nomic-embed-text)
--url	Ollama server URL (default: http://localhost:11434)
--chunk-size	Max characters per chunk (default: 1000)

az index status

az index status

Shows model name, file count, chunk count, and creation timestamp.

az index clear

az index clear

Removes the index from .agentzero/index/.

az search

Search the skill index for matching skills.

az search <query> [--json]

Flag	Description
--json	Output structured JSON

Matches against skill name, description, and tags. Results include trust tier (Verified, Community, Generated).

az link

Share tools across projects via symlinks.

az link <source>

Creates a symlink in the current project’s skill directory pointing to <source>. Useful for sharing generated or installed tools between projects.

az vault

Manage encrypted secrets.

az vault list
az vault add <provider> <name>
az vault get <provider> <name>
az vault remove <provider> <name>

az vault-import

Import secrets from a .env file into the encrypted vault.

az vault-import <path> [--dry-run]

Flag	Description
--dry-run	Show what would be imported without writing to the vault

Parses KEY=VALUE lines from the file and stores each as a vault secret.

az plugin list

List installed plugins.

az plugin list

Scans .agentzero/plugins/ for directories containing a PLUGIN.toml manifest. Displays name, version, command count, and description.

az plugin install

Install a plugin from a local directory or GitHub release.

az plugin install <source>

Format	Example	Action
owner/repo	auser/brain-plugin	Download latest GitHub release
Local path	./my-plugin	Copy from local directory

The source must contain a PLUGIN.toml and at least one .wasm file. GitHub installs verify SHA-256 checksums. Updates .agentzero/plugins/plugins.lock.

az plugin info

Show plugin details.

az plugin info <name>

Displays the plugin manifest, available commands, WASM path, and install location.

az gateway list

List configured messaging gateways.

az gateway list

Reads gateway configuration from .agentzero/gateways.toml. Shows name, type, channels, and poll interval for each gateway.

az gateway start

Start a messaging gateway in the foreground.

az gateway start <name>

Starts the named gateway, which polls for messages and routes them through the agent loop. Dangerous tools (write, edit, shell, generate_tool) are denied in gateway mode — only read-only tools are available without a human in the loop.

Gateway configuration lives in .agentzero/gateways.toml:

[[gateway]]
name = "slack-dev"
type = "slack"
token = "vault:slack/bot_token"
channels = ["#dev-agent"]
poll_interval_secs = 5

Supported gateway types: slack.

az brain init

Initialize a new brain vault.

az brain init [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--force	Force overwrite existing files
--dry-run	Print actions without executing

Creates the vault directory structure (raw/, wiki/, templates/, prompts/), starter files, configuration (.agentzero-brain.toml), and agent instruction files.

az brain today

Open or create today’s daily note.

az brain today [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--date	Date override (YYYY-MM-DD)
--open	Open in $EDITOR

az brain capture

Capture a thought to today’s daily note.

az brain capture <message> [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--date	Date override (YYYY-MM-DD)
--section	Section heading to append under (default: Capture)

Appends a timestamped entry under the specified section of the daily note.

az brain query

Search the vault for a term.

az brain query <term> [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--raw	Also search the raw directory
--json	Output as JSON
--limit	Maximum number of results (default: 50)

az brain ingest

Generate an ingest prompt for a raw file.

az brain ingest <path> [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--save-prompt	Save the prompt to wiki/reports/
--dry-run	Show what would happen without writing

az brain review

Generate an end-of-day review prompt.

az brain review [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--date	Date to review (YYYY-MM-DD)
--save-prompt	Save the prompt to wiki/reports/
--dry-run	Show what would happen without writing

az brain weekly

Generate a weekly review prompt.

az brain weekly [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--week	ISO week identifier (e.g., 2026-W20)
--save-prompt	Save the prompt to wiki/reports/

az brain health

Run vault health diagnostics.

az brain health [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--json	Output as JSON
--fix	Attempt to fix issues (not yet implemented)

Checks for missing frontmatter, unprocessed inbox files, orphan notes, empty sections, and oversized files.

az brain checkpoint

Git checkpoint the vault.

az brain checkpoint [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--message	Custom commit message
--init	Initialize a git repo if none exists
--dry-run	Show what would happen without executing

az brain ask

Ask a question using semantic search over the vault (RAG).

az brain ask <question> [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)
--limit	Number of results (default: 5)
--ollama-url	Ollama server URL (default: http://localhost:11434)
--embed-model	Embedding model (default: nomic-embed-text)
--json	Output as JSON
--reindex	Rebuild the index before querying

Requires --features rag. Builds/updates the semantic index on first use.

az brain status

Show vault status summary.

az brain status [OPTIONS]

Flag	Description
--root	Root directory for the vault (default: .)

Reports wiki note count, daily note count, raw file count, date format, raw immutability setting, and git presence.

az completions

Generate shell completions for az.

az completions <SHELL>

Supported shells: bash, zsh, fish, elvish, powershell.

Setup

# Zsh — add to ~/.zshrc
az completions zsh > ~/.zfunc/_az

# Bash
az completions bash > ~/.local/share/bash-completion/completions/az

# Fish
az completions fish > ~/.config/fish/completions/az.fish