Docs — actual CLI

Quick Start

actual analyzes your repo, fetches your team's Architectural Decision Records (ADRs), and writes them into AI context files — keeping every coding agent architecturally aligned, automatically.

Install

Choose your preferred install method:

# Homebrew (macOS & Linux)
brew install actual-software/actual/actual

# Zero-install (Node required — no Gatekeeper issues)
npx @actualai/actual adr-bot

macOS Gatekeeper

The binary isn't codesigned yet — our Apple Developer Program application is pending. After brew install, macOS will block it on first run. Remove the quarantine flag once:

xattr -dr com.apple.quarantine $(which actual)

Alternatively, use npx @actualai/actual adr-bot — it runs through Node.js and isn't subject to Gatekeeper.

Authenticate

By default, actual uses Claude Code as the AI backend. Make sure it's installed and authenticated:

npm install -g @anthropic-ai/claude-code
claude auth login
actual auth   # verify

Prefer a different AI backend? See Runners for API key alternatives.

Sync

From any git repo, run:

actual adr-bot

This analyzes your codebase, fetches matching ADRs, tailors them to your stack, and writes CLAUDE.md. Run it again whenever your architecture evolves.

Supported Languages & Frameworks

actual ships with a curated ADR bank covering the ecosystems below. Each entry represents a language + framework combination with dedicated architectural decision records tailored to real-world patterns in that stack.

TypeScript

Next.jsHeroUI

Rust

Ratatui

Python

FastAPIDjango

Java

Spring Boot

More coming soon

We're hard at work expanding language and framework coverage and continuously improving ADR quality. If your stack isn't listed yet, actual adr-bot will still analyze your repo and apply any general-purpose ADRs that fit.

Commands

All subcommands and their flags.

Command

actual adr-bot

The main command. Analyzes your repo, fetches ADRs from the bank, tailors them to your codebase, and writes the output file. Prompts for confirmation before writing.

actual adr-bot [flags]

Flag	Type	Description
`--dry-run`	bool	Preview what would change without writing any files.
`--full`	bool	With --dry-run, print the full rendered file to stdout.
`--force`	bool	Skip confirmation prompts and bypass all caches.
`--no-tailor`	bool	Skip AI tailoring; write raw ADRs as-is from the bank.
`--project <PATH>`	string	Target a specific sub-project in a monorepo (repeatable).
`--output-format <FMT>`	enum	claude-md (default) \| agents-md \| cursor-rules
`--runner <RUNNER>`	enum	AI backend: claude-cli \| anthropic-api \| openai-api \| codex-cli \| cursor-cli
`--model <MODEL>`	string	Override AI model. Runner is auto-inferred from the model name.
`--max-budget-usd <N>`	float	Spending cap per tailoring invocation (USD).
`--reset-rejections`	bool	Clear remembered ADR rejections and show all ADRs again.
`--verbose`	bool	Show detailed progress and AI runner output.
`--show-errors`	bool	Stream runner stderr in real time — useful for diagnosing hangs or auth failures.
`--no-tui`	bool	Disable the TUI; use plain line output instead.
`--api-url <URL>`	string	Override the ADR bank API endpoint.

Examples

# Preview without writing
actual adr-bot --dry-run

# Force fresh sync (bypass cache)
actual adr-bot --force

# Generate AGENTS.md instead of CLAUDE.md
actual adr-bot --output-format agents-md

# Use Anthropic API directly instead of Claude Code CLI
actual adr-bot --runner anthropic-api

# Use a specific model (runner auto-inferred)
actual adr-bot --model gpt-5.2

# Monorepo: target specific sub-projects
actual adr-bot --project packages/api --project packages/web

# Debug a hang
actual adr-bot --verbose --show-errors

Command

actual auth

Check whether the default runner (Claude Code) is installed and authenticated.

actual auth

Prints ✔ Claude Code: authenticated on success, or an error with a fix hint on failure. Use actual runners to check all backends at once.

Command

actual status

Show current config and the state of all managed output files in the current repo.

actual status
actual status --verbose

--verbose additionally shows the runner, cached analysis details, ADR counts, and telemetry status.

Command

actual config

View or edit the global config file at ~/.actualai/actual/config.yaml.

actual config show          # print current config (API keys redacted)
actual config path          # print config file location
actual config set <KEY> <VALUE>

Settable keys

Key	Default	Description
`runner`	`claude-cli`	AI backend to use for tailoring
`model`	`—`	Default model (runner is auto-inferred)
`output_format`	`claude-md`	claude-md \| agents-md \| cursor-rules
`batch_size`	`15`	ADRs per API request batch
`concurrency`	`10`	Max concurrent API requests
`invocation_timeout_secs`	`600`	Runner timeout in seconds
`max_budget_usd`	`—`	Spending cap per tailoring invocation
`max_turns`	`—`	Max conversation turns (claude-cli only)
`max_per_framework`	`—`	Max ADRs per detected framework
`include_general`	`—`	Include language-agnostic ADRs
`include_categories`	`—`	Only include these ADR categories (comma-separated)
`exclude_categories`	`—`	Exclude these ADR categories (comma-separated)
`anthropic_api_key`	`—`	Anthropic API key (stored at mode 0600)
`openai_api_key`	`—`	OpenAI API key
`cursor_api_key`	`—`	Cursor API key
`telemetry.enabled`	`true`	Enable or disable telemetry

# Examples
actual config set runner anthropic-api
actual config set model claude-sonnet-4-6
actual config set output_format agents-md
actual config set invocation_timeout_secs 1200
actual config set telemetry.enabled false
actual config set anthropic_api_key "sk-ant-..."

Command

actual runners

List all available AI backend runners and their current availability status.

actual runners

Command

actual models

List known model names grouped by runner. By default fetches live model lists from Anthropic and OpenAI APIs and annotates newly discovered models.

actual models
actual models --no-fetch   # skip live API fetch; show hardcoded list only

Command

actual cache

Clear the local analysis and tailoring cache. Cache entries expire after 7 days automatically. Use --force on actual adr-bot to bypass the cache without clearing it.

actual cache clear

Runners

A runner is the AI backend actual uses to tailor ADRs to your codebase. The default is claude-cli (Claude Code). Set a different runner with --runner or actual config set runner.

claude-cli

requires claude binary·default model: claude-sonnet-4-6

Default runner. Uses the Claude Code CLI subprocess. Short model aliases (sonnet, opus, haiku) work with this runner.

npm install -g @anthropic-ai/claude-code
claude auth login

anthropic-api

requires ANTHROPIC_API_KEY·default model: claude-sonnet-4-6

Calls the Anthropic Messages API directly. Requires a full model name (not short aliases).

export ANTHROPIC_API_KEY=sk-ant-...
# or: actual config set anthropic_api_key sk-ant-...

openai-api

requires OPENAI_API_KEY·default model: gpt-5.2

Calls the OpenAI Responses API directly.

export OPENAI_API_KEY=sk-...

codex-cli

requires codex binary·default model: gpt-5.2-codex

Uses the Codex CLI subprocess. ChatGPT OAuth (codex login) only supports the default model; for custom models, set OPENAI_API_KEY.

npm install -g @openai/codex
codex login   # or set OPENAI_API_KEY

cursor-cli

requires agent binary·default model: opus-4.6-thinking

Uses the Cursor agent CLI subprocess.

curl https://cursor.com/install -fsS | bash
cursor-agent login   # or set CURSOR_API_KEY

Runner auto-detection

When no --runner is specified, the runner is inferred from the model name: Anthropic aliases (sonnet, opus, haiku) → claude-cli then anthropic-api; full claude-* IDs → anthropic-api then claude-cli;gpt-* / o1* / o3* / o4* → codex-cli then openai-api.

Output Formats

Choose the output format with --output-format or actual config set output_format. All formats use identical managed-section markers so content outside the markers is always preserved.

claude-md

CLAUDE.md

Claude Code

agents-md

AGENTS.md

Codex CLI, OpenCode

cursor-rules

.cursor/rules/actual-policies.mdc

Cursor IDE

Managed sections are delimited by  and  markers. Any content you write outside these markers is never touched by actual adr-bot.

Configuration

Config lives at ~/.actualai/actual/config.yaml (created automatically on first run, mode 0600 on Unix). Override the path with the ACTUAL_CONFIG env var.

Environment variables

Variable	Purpose
`ACTUAL_CONFIG`	Exact path to config file (highest precedence)
`ACTUAL_CONFIG_DIR`	Directory for config (must be absolute)
`ANTHROPIC_API_KEY`	Anthropic API key (overrides config value)
`OPENAI_API_KEY`	OpenAI API key (overrides config value)
`CURSOR_API_KEY`	Cursor API key (overrides config value)
`CLAUDE_BINARY`	Override path to the claude binary
`RUST_LOG`	Log level (default: warn)

Cache

Analysis and tailoring results are cached locally for 7 days (keyed to git HEAD + config hash). Run actual cache clear to wipe, or pass --force to bypass on a single sync.

Troubleshooting

Common errors

Claude Code is not installed

npm install -g @anthropic-ai/claude-code

Claude Code is not authenticated

claude auth login

No runner available for model '…'

Install a runner or set an API key. Run actual runners to see what's available.

Runner timed out after 600s

actual config set invocation_timeout_secs 1200

Insufficient credits

Add credits at your provider's billing page, or use --max-budget-usd to cap spend.

Analysis returned no projects

Make sure you're running from inside a git repo. For monorepos, use --project <PATH>.

Debug flags

# See full AI runner output
actual adr-bot --verbose

# Stream runner stderr in real time (auth prompts, permission errors)
actual adr-bot --show-errors

# Disable TUI for plain output (useful in CI)
actual adr-bot --no-tui

# Full debug logging
RUST_LOG=debug actual adr-bot --no-tui 2>&1

Exit codes

Code	Meaning
`0`	Success
`1`	General runtime error
`2`	Auth / setup error (binary not found, not authenticated, API key missing)
`3`	Billing / API error (credits too low)
`4`	User cancelled
`5`	I/O error (permissions, disk space)

Getting started

Quick Start

Install

Authenticate

Sync

Supported Languages & Frameworks

Commands

actual adr-bot

Examples

actual auth

actual status

actual config

Settable keys

actual runners

actual models

actual cache

Runners

Output Formats

Configuration

Environment variables

Cache

Troubleshooting

Common errors

Debug flags

Exit codes