Documentation

Overview

ai is a single-binary Rust CLI agent. ai run "PROMPT" performs a one-shot request (or read the prompt from stdin); bare ai starts an interactive session. The response streams to stdout, while thinking and tool calls go to stderr, so results pipe cleanly into other commands.

The model starts with only what you give it — no filesystem, no network, no shell. Every capability beyond a plain answer is opt-in via CLI flags or a declarative policy file. Two exceptions are on by default: local semantic memory (disable with --no-memory) and session persistence (disable with --no-session).

Quickstart

Run ai setup once to pick a provider and model. After that, ai (no arguments) drops you into an interactive session that remembers the conversation and can resume it later.

Commands & Flags

Value flags accept either --flag value or --flag=value.

Commands

Global flags

Examples

Configuration

Config is YAML at ~/.config/ai/config.yaml (override with -c). Every field is optional; CLI flags and env vars override config values. Unknown keys warn; ai setup rejects them.

Environment Variables

An API key may be a literal or env:VAR_NAME; env: is preferred so secrets stay out of the file.

Field Reference

Providers

ai speaks the OpenAI and Anthropic APIs natively. Any other provider works by setting api_base to its compatible endpoint and choosing the matching flavor (openai or anthropic). Built-ins cover OpenAI, Anthropic, Ollama, Groq, DeepSeek, Google Gemini, Mistral, OpenRouter, xAI, and llamafile; ai setup can also browse the full models.dev catalog.

Example configs

Access Policy

The policy engine controls what files, commands, and web resources the model can access. Rules are evaluated first-match: the first matching Allow or Deny rule wins. CLI flags (-r, -w, -x, --web) are prepended to policy-file rules and take precedence.

Actions

Policy File Syntax

One rule per line. # starts a comment.

Path Matching

Path patterns support glob wildcards and are segment-aware: /tmp matches /tmp/foo.txt but not /tmpfile. Paths are resolved (symlinks included) before the policy is consulted, so a deny inside an allowed tree is honored. ~ is expanded.

Execute Patterns

The execute tool always runs. 150+ built-in commands (echo, cat, grep, sed, git, curl, …) run inside a virtual bash interpreter (bashkit) and are governed by filesystem read/write policy, not execute permissions. External commands (e.g. cargo, npm, python) are checked against the execute allowlist. See Filesystem & Containers for how containers change this.

Interactive Ask Mode

With -i/--ask, an unmatched action prompts you and remembers the choice for the session: allow once, remember the exact target, remember its directory, or deny.

Filesystem & Containers

Every user-supplied path is resolved and authorized in one checked layer before the operation, so deny rules inside an allowed tree hold and symlink escapes are blocked.

External commands run through bashkit. In-process builtins run without a grant; external commands require -x unless a container is active. When a container is configured (-X/--container[=IMAGE], default debian:stable-slim, or container.default_image), a single session container starts at agent startup and every execute command runs inside it:

• Policy read roots are bind-mounted read-only, write roots read-write; the host filesystem is otherwise invisible.
• The container gets no network unless web access is granted (container.network: policy).
• --no-container forces host execution; --container-runtime picks docker/podman.
• --yolo does not disable the container — it relaxes tool policy only. Whole-filesystem (**) grants are not mountable and are warned about.

Sessions

Sessions persist the full message log (tool calls and results included) to JSON. Each session records its provider and model; resuming under a different pair forks a fresh session instead of replaying an incompatible history.

ai run and bare ai automatically continue the newest session when it is less than 60 minutes old and its provider/model match; otherwise a new session starts. One-off sessions are saved only after a successful run. Pass --no-session to run stateless.

In-Session Commands

Memory

Memory is enabled by default and stored in a SQLite database (memory.db). Facts and past exchanges are embedded locally (ONNX via fastembed) and searched with sqlite-vec, so nothing leaves your machine. Relevant hits and transcript excerpts are injected per message, each shown with a cosine match score.

Four tools back this: memory_add (text, optional tags, origin), memory_search, memory_get (fetch one entry by key), and memory_delete. Tuning keys: embedding_model (default multilingual-e5-small) and memory_max_distance (lower is stricter). Disable with --no-memory.

Memory Maintenance

ai dream keeps memory healthy. It runs over a work pool (--jobs N, config dream.jobs, default 4):

1. extract — distill durable facts from unprocessed transcript tuples.
2. skills — when skills.auto_create is true, review sessions with at least skills.min_tuples unreviewed exchanges and author or update skills.
3. prune — delete processed transcripts older than 7 days (skill-pending sessions are held back).
4. judge — review entries unused and unjudged for 30 days and delete obsolete ones.

An interactive session offers to run maintenance at exit when the backlog is large, and dream.auto: true runs it automatically at the end of every saved session.

Skills

A skill is a SKILL.md file (YAML front matter with name and description) under the skills directory (skills.dir, default <data-dir>/ai/skills). Skills are listed in the system prompt, and the model loads one on demand with the load_skill tool, which returns the full body plus the absolute paths of any bundled files (scripts, references). The skills folder is granted read access automatically.

With skills.auto_create: true, ai dream can author skills from past sessions. AI-created skills are tagged origin: ai and are the only ones the agent may modify or delete; they appear as (AI-created) in the prompt. Inspect and remove them with ai skills list and ai skills delete NAME.

Web & Search

Web access is off unless granted: --web for everything, or --web-fetch URL / --web-search QUERY for narrower grants. web_fetch retrieves a page and converts it to readable text; web_search uses an ordered ladder of providers configured in search.providers:

• Keyed APIs — brave, tavily, exa, serper. An omitted api_key falls back to BRAVE_API_KEY / TAVILY_API_KEY / EXA_API_KEY / SERPER_API_KEY.
• SearXNG — a normal entry that needs a url (queried via its JSON API).
• Keyless scrapers — duckduckgo, google, bing.

The first provider that succeeds wins; a listed provider missing credentials is skipped with a warning. --probe-web QUERY tests the configured providers.

MCP Tool Servers

Connect Model Context Protocol servers to extend ai with external tools — IDE integrations, database agents, API gateways. Use --tool URL for one run, or declare servers in config:

Config servers and --tool URLs are merged and deduplicated. A config server that fails to connect is skipped with a warning; a --tool failure aborts startup.

Built-in Tools

30+ built-in tools are conditionally registered based on active policy rules.

Filesystem

Execution

Search

Web

Browser

Memory & other

Inline Help

The agent has a manual tool that serves this documentation, the example config, and the generated CLI help. Ask it questions about ai itself — flags, config keys, or how a feature works — and it answers from the manual rather than guessing.

In an interactive session, /help lists the slash commands and reminds you that you can just ask.

Output & Thinking

Assistant markdown is rendered to ANSI on a terminal and left as raw markdown when piped. A first-token spinner appears while waiting. Use --no-color (or NO_COLOR) to disable styling.

Thinking tokens are counted in the token stats, shown as (in, thinking, out).

Setup

ai setup has two phases. First a deterministic wizard: reuse an existing config or detected credentials, otherwise pick a provider and model — browsing the models.dev catalog or entering a custom URL — and confirm with a small connection test. Then an AI conversation edits the rest of the config, saving through a sandboxed, approval-gated tool. The API key is never sent to the model, and an existing config is backed up to config.yaml.bak.

Prefer api_key: env:VAR_NAME so keys stay out of the file. Afterwards, ai is ready to use.