actual — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited actual (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
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 actualInstall 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
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.
grep -l "managed:actual-start" CLAUDE.md AGENTS.md 2>/dev/nullProceed — the agent session already has this context.
actual adr-bot --dry-runReview the output. If relevant ADRs exist, run actual adr-bot to sync them into CLAUDE.md / AGENTS.md before starting work.
| 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/logoutdrive the Actual Advisor — a signed-in, org-scoped Q&A surface separate from the runner auth thatauthreports. See Asking the Advisor.
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 | 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) |
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.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.00For the complete 13-step sync internals, see references/sync-workflow.md.Follow this pattern whenever running sync. Do NOT skip pre-flight.
command -v actual # Must succeed before anything elseIf missing, follow the install steps in CLI Not Installed above. Do NOT proceed until actual --version succeeds.
actual runners # Verify runner is available
actual auth # Verify authentication (for claude-cli)
actual config show # Review current configurationIf any check shows a problem, diagnose and fix before proceeding.
actual adr-bot --dry-run [--full] [user's flags]Show the user what would change. Let them review.
Ask user if they want to proceed. If no, stop.
actual adr-bot [user's flags]Match the error against the troubleshooting table below. For full error details, load references/error-catalog.md.
Apply the fix, then return to step 1 to verify.
For comprehensive environment checks, run the bundled diagnostic script:
bash .claude/skills/actual/scripts/diagnose.shThis 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).
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:
# 1. Sign in via browser OAuth (grants the adr:query and adr:review scopes).
actual login
# Headless or over SSH? Print the URL instead of opening a browser:
actual login --no-browser
# 2. Ask an org-scoped architecture question.
actual advisor "Which router should new Next.js pages use?"
# 3. Check identity, or sign out when finished.
actual whoami
actual logoutThe 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.
| 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.| 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 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.| 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:
For full format details and merge internals, see references/output-formats.md.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 |
For anything not covered by this skill or its reference files, fetch the full CLI documentation:
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.