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

Detect with:

command -v actual

Install options (try in this order):

npm install -g @actualai/actual

brew install actual-software/actual/actual

actual-software/actual-releases

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.

1. Check for managed section markers in CLAUDE.md or AGENTS.md:

   grep -l "managed:actual-start" CLAUDE.md AGENTS.md 2>/dev/null
   

2. If markers found: ADR context is already loaded into the output file. Proceed — the agent session already has this context.
3. 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.
4. If no markers and no CLI: proceed without. Do not block the user.

Commands

actual adr-bot

--dry-run [--full]

--force

--no-tailor

--project PATH

--model

--runner

--verbose

--reset-rejections

--max-budget-usd

--no-tui

--output-format

--show-errors

actual status

--verbose

actual auth

actual config show

actual config set <key> <value>

actual config path

actual runners

actual models

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

claude

claude auth login

ANTHROPIC_API_KEY

OPENAI_API_KEY

codex

OPENAI_API_KEY

codex login

agent

CURSOR_API_KEY

Model-to-Runner Inference

The CLI auto-selects a runner from the model name:

sonnet

opus

haiku

claude-*

gpt-*

o1*

o3*

o4*

chatgpt-*

codex-*

gpt-*-codex*

For deep runner details (install steps, compatibility, special behaviors), see

references/runner-guide.md

.

Sync Quick Reference

The most common sync patterns:

# Preview what sync would do (safe, no file changes)
actual adr-bot --dry-run

# Preview with full content
actual adr-bot --dry-run --full

# Run sync, skip confirmation prompts
actual adr-bot --force

# Sync specific subdirectories only (monorepo)
actual adr-bot --project services/api --project services/web

# Use a specific runner/model
actual adr-bot --runner anthropic-api --model claude-sonnet-4-6

# Skip AI tailoring (use raw ADRs)
actual adr-bot --no-tailor

# Re-offer previously rejected ADRs
actual adr-bot --reset-rejections

# Set spending cap
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       # Must succeed before anything else

If missing, follow the install steps in CLI Not Installed above. Do NOT proceed until

actual --version

1. Pre-flight (LOW freedom -- exact commands)

actual runners          # Verify runner is available
actual auth             # Verify authentication (for claude-cli)
actual config show      # Review current configuration

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

Troubleshooting Quick Reference

claude

claude auth login

codex

OPENAI_API_KEY

codex login

agent

ANTHROPIC_API_KEY

OPENAI_API_KEY

OPENAI_API_KEY

invocation_timeout_secs

actual config show

--no-tailor

For full error details with hints and diagnosis steps, see

references/error-catalog.md

.

Exit Code Categories

Config Quick Reference

Config file:

~/.actualai/actual/config.yaml

ACTUAL_CONFIG

ACTUAL_CONFIG_DIR

Most-used config keys:

runner

model

output_format

batch_size

concurrency

invocation_timeout_secs

max_budget_usd

For all 18 config keys with validation rules, see

references/config-reference.md

.

Output Formats

CLAUDE.md

# Project Guidelines

AGENTS.md

# Project Guidelines

.cursor/rules/actual-policies.mdc

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:

references/sync-workflow.md

references/runner-guide.md

references/error-catalog.md

references/config-reference.md

references/output-formats.md