Actual Software Actual Skill Actual

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):

For one-off use without installing globally:

npx @actualai/actual adr-bot [flags]

After install, verify: actual --version

Commands

Platform Identity & Advisor

These commands talk to the Actual AI platform (your account/org) and are separate from actual auth — actual auth only checks the local coding-agent/runner (claude/codex/cursor) that adr-bot drives. login/logout/whoami manage your Actual AI platform identity; advisor asks org-scoped architecture questions against it. (The runner/model sections below pertain to adr-bot, not to these.)

Endpoint config — the platform URL is supplied per command; there is no production default baked in yet.

• login reads --api-url <url> or the ACTUAL_AUTH_URL env var.
• advisor reads --api-url <url> or the ACTUAL_API_URL env var.
• OAuth client_id/scopes default to actual-cli and openid profile offline_access adr:query adr:review (override via ACTUAL_OAUTH_CLIENT_ID / ACTUAL_OAUTH_SCOPES).

login — interactive; hand off to the human

actual login runs a browser OAuth flow (auth-code + PKCE + a 127.0.0.1 loopback). It needs a human at a browser, so an agent cannot complete it inside a non-interactive shell. Drive it like this:

1. First check whether the user is already signed in with actual whoami (no network; non-zero exit / "Not signed in" when logged out). If signed in, skip login.
2. If not signed in, ask the human to run login, or run it for them and surface the URL:

   actual login --no-browser       # prints the authorize URL instead of opening a browser
   actual login --org <org-id>     # multi-org accounts: pre-select an org (single-org auto-selects)
   

   With --no-browser, give the printed URL to the user to open; the CLI waits on the loopback redirect to finish the sign-in.
3. A multi-org user who omits --org picks the org on the consent page; if the redirect times out, re-run with --org <id>.

Do not attempt to script the browser/consent step — treat login as a human handoff, then resume automation once whoami succeeds.

whoami — safe, non-interactive

actual whoami

Prints the cached identity — Organization, Account, Member, Scopes — with no network call. Use it as the pre-flight gate before advisor: exit code 2 ("Not signed in to Actual AI") means run login first.

logout

actual logout

Best-effort server-side token revoke, then always clears local credentials. Safe and non-interactive.

advisor — non-interactive, async query

actual advisor "<question>" asks an org-scoped architecture question. It is agent-friendly (no TTY required): it starts an async job, polls to completion, and prints a plain-text summary followed by the related ADRs. Progress ("advisor thinking…") goes to stderr; the answer goes to stdout.

actual advisor "How should I handle database access in a new service?"

# point at a local/staging endpoint — one export steers it; --api-url overrides
ACTUAL_API_URL=https://your-advisor-endpoint actual advisor "…"

# scope to an org / a connected repo (both UUIDs)
actual advisor "…" --org <org-uuid> --repo <repo-uuid>

Requires a valid signed-in session — NotLoggedIn (exit 2) means run login first. The advisor transparently refreshes an expired token before the call. Output is human-readable text today (no --json flag yet).

For the full OAuth flow, scopes, multi-org selection, the advisor poll model, and org/repo scoping, see references/platform-advisor.md.

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

Model-to-Runner Inference

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

For deep runner details (install steps, compatibility, special behaviors), see references/runner-guide.md.

Non-Interactive Environments

This skill runs inside coding agents (Claude Code, Codex, Cursor) where the Bash tool does not provide a TTY. The CLI's TUI prompts and confirmation dialogs will fail with TerminalIOError unless disabled.

Always pass --force --no-tui on every actual adr-bot invocation:

• --no-tui disables TUI rendering that requires a terminal
• --force skips interactive confirmation prompts that cannot receive input

Use the agent's built-in question/confirmation tools (e.g., AskUserQuestion) for user confirmation instead of relying on CLI prompts.

Sync Quick Reference

The most common sync patterns:

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

# Preview with full content
actual adr-bot --dry-run --full --force --no-tui

# Run sync
actual adr-bot --force --no-tui

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

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

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

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

# Set spending cap
actual adr-bot --force --no-tui --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 succeeds.

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 --force --no-tui [--full] [user's flags]

Show the user what would change. Let them review.

3. Confirm (HIGH freedom)

Ask user if they want to proceed using the agent's built-in tools (e.g., AskUserQuestion). Do NOT rely on CLI prompts — they will fail in non-interactive shells. If no, stop.

4. Execute (LOW freedom -- exact command)

actual adr-bot --force --no-tui [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

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 (override with ACTUAL_CONFIG or ACTUAL_CONFIG_DIR env vars).

Most-used config keys:

For all 18 config keys with validation rules, see references/config-reference.md.

Output Formats

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:

Additional Resources

For anything not covered by this skill or its reference files, fetch the full CLI documentation:

• Full docs (Markdown): https://cli.actual.ai/docs.md — complete command reference, all flags, runners, output formats, config keys, and troubleshooting
• LLM summary: https://cli.actual.ai/llms.txt — concise machine-readable overview

Source: actual-software/actual-skill — distributed by TomeVault.