| name | actual |
| description | Feature-complete companion for the actual CLI, an ADR-powered CLAUDE.md/AGENTS.md generator. Runs and troubleshoots actual adr-bot, status, auth, config, runners, and models, and drives the Actual Advisor (login, advisor, whoami, logout) for org-scoped architecture questions. Covers all 5 runners (claude-cli, anthropic-api, openai-api, codex-cli, cursor-cli), all model patterns, all 3 output formats (claude-md, agents-md, cursor-rules), and all error types. Use when working with the actual CLI, running actual adr-bot, configuring runners or models, troubleshooting errors, managing output files, or asking the Advisor what your team's ADRs say about a design choice. |
| argument-hint | [question or command] e.g. 'run sync', 'set up anthropic-api', 'fix ClaudeNotFound' |
| metadata | {"openclaw":{"requires":{"bins":["actual"]},"primaryEnv":"ANTHROPIC_API_KEY","homepage":"https://cli.actual.ai"}} |
actual CLI Companion
Inline knowledge and operational workflows for the actual CLI. Read this file first; load reference files only when you need deeper detail for a specific topic.
CLI Not Installed
If the actual binary is not in PATH, stop and help the user install it before doing anything else. All commands, pre-flight checks, and diagnostics require the CLI.
Detect with:
command -v actual
Install options (try in this order):
| Method | Command |
|---|
| npm/npx (quickest) | npm install -g @actualai/actual |
| Homebrew (macOS/Linux) | brew install actual-software/actual/actual |
| GitHub Release (manual) | Download from actual-software/actual-releases on GitHub |
For one-off use without installing globally:
npx @actualai/actual adr-bot [flags]
After install, verify: actual --version
ADR Pre-Check (OpenClaw)
Before creating a new skill, component, or feature, check whether the project
has ADR context available. This ensures new work aligns with existing
architectural decisions.
- Check for managed section markers in CLAUDE.md or AGENTS.md:
grep -l "managed:actual-start" CLAUDE.md AGENTS.md 2>/dev/null
- If markers found: ADR context is already loaded into the output file.
Proceed — the agent session already has this context.
- If no markers but
actual CLI is available:
actual adr-bot --dry-run
Review the output. If relevant ADRs exist, run actual adr-bot to sync
them into CLAUDE.md / AGENTS.md before starting work.
- If no markers and no CLI: proceed without. Do not block the user.
Commands
| Command | Purpose | Key Flags |
|---|
actual adr-bot | Analyze repo, fetch ADRs, tailor, write output | --dry-run [--full], --force, --no-tailor, --project PATH, --model, --runner, --verbose, --reset-rejections, --max-budget-usd, --no-tui, --output-format, --show-errors |
actual status | Check output file state | --verbose |
actual auth | Check authentication status | (none) |
actual config show | Display current config | (none) |
actual config set <key> <value> | Set a config value | (none) |
actual config path | Print config file path | (none) |
actual runners | List available runners | (none) |
actual models | List known models by runner | (none) |
actual login | Sign in to Actual AI (required for the Advisor) | --no-browser, --org, --api-url |
actual advisor "<question>" | Ask an org-scoped architecture question | --repo, --org, --api-url |
actual whoami | Show the signed-in identity (no network call) | (none) |
actual logout | Sign out and clear local credentials | (none) |
login / advisor / whoami / logout drive the Actual Advisor — a signed-in, org-scoped Q&A surface separate from the runner auth that auth reports. See Asking the Advisor.
Runner Decision Tree
Use this to determine which runner a user needs:
Has claude binary installed?
YES -> claude-cli (default runner, no API key needed)
NO -> Do they want Anthropic models?
YES -> anthropic-api (needs ANTHROPIC_API_KEY)
NO -> Do they want OpenAI models?
YES -> codex-cli or openai-api (needs OPENAI_API_KEY)
NO -> cursor-cli (needs agent binary, optional CURSOR_API_KEY)
Runner Summary
| Runner | Binary | Auth | Default Model |
|---|
| claude-cli | claude | claude auth login | claude-sonnet-4-6 |
| anthropic-api | (none) | ANTHROPIC_API_KEY | claude-sonnet-4-6 |
| openai-api | (none) | OPENAI_API_KEY | gpt-5.2 |
| codex-cli | codex | OPENAI_API_KEY or codex login (ChatGPT OAuth) | gpt-5.2 |
| cursor-cli | agent | Optional CURSOR_API_KEY | (cursor default) |
Model-to-Runner Inference
The CLI auto-selects a runner from the model name:
| Model Pattern | Inferred Runner |
|---|
sonnet, opus, haiku (short aliases) | claude-cli |
claude-* (full names) | anthropic-api |
gpt-*, o1*, o3*, o4*, chatgpt-* | codex-cli |
codex-*, gpt-*-codex* | codex-cli |
| Unrecognized | Error with suggestions |
For deep runner details (install steps, compatibility, special behaviors), see references/runner-guide.md.
Sync Quick Reference
The most common sync patterns:
actual adr-bot --dry-run
actual adr-bot --dry-run --full
actual adr-bot --force
actual adr-bot --project services/api --project services/web
actual adr-bot --runner anthropic-api --model claude-sonnet-4-6
actual adr-bot --no-tailor
actual adr-bot --reset-rejections
actual adr-bot --max-budget-usd 5.00
For the complete 13-step sync internals, see references/sync-workflow.md.
Operational Workflow: Running Sync
Follow this pattern whenever running sync. Do NOT skip pre-flight.
0. Verify CLI installed (LOW freedom -- exact check)
command -v actual
If missing, follow the install steps in CLI Not Installed above. Do NOT proceed until actual --version succeeds.
1. Pre-flight (LOW freedom -- exact commands)
actual runners
actual auth
actual config show
If any check shows a problem, diagnose and fix before proceeding.
2. Dry-run (LOW freedom -- exact command)
actual adr-bot --dry-run [--full] [user's flags]
Show the user what would change. Let them review.
3. Confirm (HIGH freedom)
Ask user if they want to proceed. If no, stop.
4. Execute (LOW freedom -- exact command)
actual adr-bot [user's flags]
5. On failure: Diagnose
Match the error against the troubleshooting table below. For full error details, load references/error-catalog.md.
6. Fix and retry
Apply the fix, then return to step 1 to verify.
Operational Workflow: Diagnostics
For comprehensive environment checks, run the bundled diagnostic script:
bash .claude/skills/actual/scripts/diagnose.sh
This checks all binaries, auth status, environment variables, config, and output files in one pass. It is read-only and never modifies anything.
Use inline commands instead when checking a single thing (e.g., just actual auth).
Asking the Advisor
Beyond generating guardrails, the actual CLI can answer architecture questions on demand. The advisor command queries your organization's ADRs and returns guidance grounded in your team's real decisions — reach for it when the user asks "what's our convention for X?" or "does our architecture allow Y?" instead of answering from general knowledge.
The Advisor needs a signed-in Actual AI account, which is separate from the runner auth that actual auth reports. The flow is sign in, ask, then sign out when done:
actual login
actual login --no-browser
actual advisor "Which router should new Next.js pages use?"
actual whoami
actual logout
The Advisor prints the answer followed by the related ADRs it drew on, each with a confidence score. Scope a question to one connected repository with --repo <UUID> or to a specific organization with --org.
Both login and advisor default to the production Actual AI endpoints out of the box (https://app.actual.ai for sign-in, the prod api-service for queries), so no URL flag is needed for normal use. Pass --api-url, or set ACTUAL_AUTH_URL / ACTUAL_API_URL, only to target staging or a local mock. whoami reads the local credentials and makes no network call (it errors when signed out); logout revokes the session server-side on a best-effort basis and then always clears the local credentials, even offline.
Troubleshooting Quick Reference
| Error | Exit Code | Likely Cause | Quick Fix |
|---|
| ClaudeNotFound | 2 | claude binary not in PATH | Install Claude Code CLI |
| ClaudeNotAuthenticated | 2 | Not logged in | Run claude auth login |
| CodexNotFound | 2 | codex binary not in PATH | Install Codex CLI |
| CodexNotAuthenticated | 2 | No auth for codex | Set OPENAI_API_KEY or run codex login |
| CursorNotFound | 2 | agent binary not in PATH | Install Cursor CLI |
| ApiKeyMissing | 2 | Required env var not set | Set ANTHROPIC_API_KEY or OPENAI_API_KEY |
| CodexCliModelRequiresApiKey | 2 | ChatGPT OAuth with explicit model | Set OPENAI_API_KEY (OAuth only supports default model) |
| CreditBalanceTooLow | 3 | Insufficient API credits | Add credits to account |
| ApiError | 3 | API request failed | Check API URL, network, credentials |
| ApiResponseError | 3 | Unexpected API response | Check API status, retry |
| RunnerFailed | 1 | Runner process errored | Check runner output, logs |
| RunnerOutputParse | 1 | Could not parse runner output | Check model compatibility |
| RunnerTimeout | 1 | Runner exceeded time limit | Increase invocation_timeout_secs |
| ConfigError | 1 | Invalid config file | Check YAML syntax, run actual config show |
| AnalysisEmpty | 1 | No analysis results | Check project path, repo content |
| TailoringValidationError | 1 | Tailored output invalid | Retry, or use --no-tailor |
| IoError | 5 | File I/O failure | Check permissions, disk space |
| UserCancelled | 4 | User cancelled operation | (intentional) |
For full error details with hints and diagnosis steps, see references/error-catalog.md.
Exit Code Categories
| Code | Category | Errors |
|---|
| 1 | General / runtime | RunnerFailed, RunnerOutputParse, ConfigError, RunnerTimeout, AnalysisEmpty, TailoringValidationError, InternalError, TerminalIOError |
| 2 | Auth / setup | ClaudeNotFound, ClaudeNotAuthenticated, CodexNotFound, CodexNotAuthenticated, CursorNotFound, ApiKeyMissing, CodexCliModelRequiresApiKey |
| 3 | Billing / API | CreditBalanceTooLow, ApiError, ApiResponseError |
| 4 | User cancelled | UserCancelled |
| 5 | I/O | IoError |
Config Quick Reference
Config file: ~/.actualai/actual/config.yaml (override with ACTUAL_CONFIG or ACTUAL_CONFIG_DIR env vars).
Most-used config keys:
| Key | Default | Purpose |
|---|
runner | claude-cli | Which runner to use |
model | claude-sonnet-4-6 | Model for Anthropic runners |
output_format | claude-md | Output format: claude-md, agents-md, cursor-rules |
batch_size | 15 | ADRs per batch (min 1) |
concurrency | 10 | Parallel requests (min 1) |
invocation_timeout_secs | 600 | Runner timeout in seconds (min 1) |
max_budget_usd | (none) | Spending cap (positive, finite) |
For all 18 config keys with validation rules, see references/config-reference.md.
Output Formats
| Format | File | Header |
|---|
| claude-md (default) | CLAUDE.md | # Project Guidelines |
| agents-md | AGENTS.md | # Project Guidelines |
| cursor-rules | .cursor/rules/actual-policies.mdc | YAML frontmatter (alwaysApply: true) |
Managed sections use markers: <!-- managed:actual-start --> / <!-- managed:actual-end -->.
Merge behavior:
- New root file: header + managed section
- New subdir file: managed section only (no header)
- Existing with markers: replace between markers, preserve surrounding content
- Existing without markers: append managed section
For full format details and merge internals, see references/output-formats.md.
Reference Files
Load these only when you need deeper detail on a specific topic:
| File | When to Load |
|---|
references/sync-workflow.md | Debugging sync failures, understanding sync internals |
references/runner-guide.md | Setting up a runner, model compatibility, runner-specific behavior |
references/error-catalog.md | Troubleshooting a specific error with full diagnosis steps |
references/config-reference.md | Looking up config keys, validation rules, dotpath syntax |
references/output-formats.md | Output format questions, managed section behavior, merge logic |
Additional Resources
For anything not covered by this skill or its reference files, fetch the full CLI documentation:
