actual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

actual CLI Companion

actual CLI 配套指南

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.

actual CLI的嵌入式知识与操作工作流。请先阅读本文档；仅当需要特定主题的详细信息时，再加载参考文件。

CLI Not Installed

未安装CLI

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:

bash

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:

bash

npx @actualai/actual adr-bot [flags]

After install, verify:

actual --version

如果

actual

二进制文件不在PATH中，请先停止当前操作，帮助用户完成安装，再进行其他操作。所有命令、预检检查和诊断都需要依赖该CLI。

检测命令：

bash

command -v actual

安装选项（按以下顺序尝试）：

方法	命令
npm/npx（最快）	`npm install -g @actualai/actual`
Homebrew（macOS/Linux）	`brew install actual-software/actual/actual`
GitHub Release（手动）	从GitHub的 `actual-software/actual-releases` 下载

无需全局安装的一次性使用方式：

bash

npx @actualai/actual adr-bot [flags]

安装完成后，验证：

actual --version

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 adr-bot`	分析仓库、获取ADR、定制内容、写入输出	`--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)

使用以下逻辑确定用户需要的运行器：

是否已安装claude二进制文件？
  是 -> claude-cli（默认运行器，无需API密钥）
  否 -> 是否需要Anthropic模型？
           是 -> anthropic-api（需要ANTHROPIC_API_KEY）
           否 -> 是否需要OpenAI模型？
                    是 -> codex-cli或openai-api（需要OPENAI_API_KEY）
                    否 -> cursor-cli（需要agent二进制文件，可选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)

运行器	二进制文件	认证方式	默认模型
claude-cli	`claude`	`claude auth login`	claude-sonnet-4-6
anthropic-api	(无)	`ANTHROPIC_API_KEY`	claude-sonnet-4-6
openai-api	(无)	`OPENAI_API_KEY`	gpt-5.2
codex-cli	`codex`	`OPENAI_API_KEY` 或 `codex login` （ChatGPT OAuth）	gpt-5.2
cursor-cli	`agent`	可选 `CURSOR_API_KEY`	(cursor默认模型)

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
.

CLI会根据模型名称自动选择运行器：

模型模式	推断出的运行器
`sonnet` , `opus` , `haiku` （短别名）	claude-cli
`claude-*` （全名）	anthropic-api
`gpt-` , `o1` , `o3` , `o4` , `chatgpt-*`	codex-cli
`codex-` , `gpt--codex*`	codex-cli
无法识别	报错并给出建议

如需运行器的详细信息（安装步骤、兼容性、特殊行为），请查看
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.

本技能运行在编码代理（Claude Code、Codex、Cursor）中，这些环境的Bash工具不提供TTY。除非禁用，否则CLI的TUI提示和确认对话框会因

TerminalIOError

失败。

在每次调用
actual adr-bot
时，请务必添加
--force --no-tui
参数：

```
--no-tui
```
禁用需要终端的TUI渲染
```
--force
```
跳过无法接收输入的交互式确认提示

请使用代理内置的问题/确认工具（如

AskUserQuestion

）获取用户确认，不要依赖CLI提示。

Sync Quick Reference

同步快速参考

The most common sync patterns:

bash

undefined

最常用的同步模式：

bash

undefined

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)

跳过AI定制（使用原始ADR）

actual adr-bot --force --no-tui --no-tailor

Re-offer previously rejected ADRs

重新提供之前被拒绝的ADR

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`.

actual adr-bot --force --no-tui --max-budget-usd 5.00


> 如需完整的13步同步内部流程，请查看`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)

0. 验证CLI已安装（低自由度——严格检查）

bash

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.

bash

command -v actual       # 必须执行成功才能进行后续操作

如果未找到，请按照上方未安装CLI中的步骤安装。在

actual --version

执行成功前，请勿继续。

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

1. 预检（低自由度——严格命令）

bash

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.

bash

actual runners          # 验证运行器可用
actual auth             # 验证认证状态（针对claude-cli）
actual config show      # 查看当前配置

如果任何检查出现问题，请先诊断并修复，再继续。

2. Dry-run (LOW freedom -- exact command)

2. 试运行（低自由度——严格命令）

bash

actual adr-bot --dry-run --force --no-tui [--full] [user's flags]

Show the user what would change. Let them review.

bash

actual adr-bot --dry-run --force --no-tui [--full] [用户参数]

向用户展示会发生的变更，等待用户审核。

3. Confirm (HIGH freedom)

3. 确认（高自由度）

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.

使用代理内置工具（如

AskUserQuestion

）询问用户是否继续。不要依赖CLI提示——它们在非交互式shell中会失败。如果用户拒绝，停止操作。

4. Execute (LOW freedom -- exact command)

4. 执行（低自由度——严格命令）

bash

actual adr-bot --force --no-tui [user's flags]

bash

actual adr-bot --force --no-tui [用户参数]

5. On failure: Diagnose

5. 失败时：诊断

Match the error against the troubleshooting table below. For full error details, load

references/error-catalog.md

将错误与下方的故障排查表匹配。如需完整错误详情，请加载

references/error-catalog.md

。

6. Fix and retry

6. 修复并重试

Apply the fix, then return to step 1 to verify.

应用修复方案，然后回到步骤1进行验证。

Operational Workflow: Diagnostics

操作工作流：诊断

For comprehensive environment checks, run the bundled diagnostic script:

bash

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

如需全面的环境检查，请运行内置的诊断脚本：

bash

bash .claude/skills/actual/scripts/diagnose.sh

该脚本会一次性检查所有二进制文件、认证状态、环境变量、配置和输出文件。它是只读的，不会修改任何内容。

当仅需检查单个项时，请使用单行命令（例如仅

actual auth

）。

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`
TerminalIOError	1	CLI needs a TTY (non-interactive shell)	Add `--force --no-tui` flags
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
.

错误	退出码	可能原因	快速修复
ClaudeNotFound	2	`claude` 二进制文件不在PATH中	安装Claude Code CLI
ClaudeNotAuthenticated	2	未登录	运行 `claude auth login`
CodexNotFound	2	`codex` 二进制文件不在PATH中	安装Codex CLI
CodexNotAuthenticated	2	Codex未认证	设置 `OPENAI_API_KEY` 或运行 `codex login`
CursorNotFound	2	`agent` 二进制文件不在PATH中	安装Cursor CLI
ApiKeyMissing	2	缺少必需的环境变量	设置 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`
CodexCliModelRequiresApiKey	2	使用ChatGPT OAuth并指定了模型	设置 `OPENAI_API_KEY` （OAuth仅支持默认模型）
CreditBalanceTooLow	3	API余额不足	为账户充值
ApiError	3	API请求失败	检查API地址、网络、凭证
ApiResponseError	3	API响应异常	检查API状态，重试
RunnerFailed	1	运行器进程出错	检查运行器输出、日志
RunnerOutputParse	1	无法解析运行器输出	检查模型兼容性
RunnerTimeout	1	运行器超时	增加 `invocation_timeout_secs`
ConfigError	1	配置文件无效	检查YAML语法，运行 `actual config show`
AnalysisEmpty	1	无分析结果	检查项目路径、仓库内容
TailoringValidationError	1	定制输出无效	重试，或使用 `--no-tailor`
TerminalIOError	1	CLI需要TTY（非交互式shell）	添加 `--force --no-tui` 参数
IoError	5	文件I/O失败	检查权限、磁盘空间
UserCancelled	4	用户取消操作	(正常情况)

如需完整错误详情及诊断步骤，请查看
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

代码	分类	对应错误
1	通用/运行时	RunnerFailed, RunnerOutputParse, ConfigError, RunnerTimeout, AnalysisEmpty, TailoringValidationError, InternalError, TerminalIOError
2	认证/设置	ClaudeNotFound, ClaudeNotAuthenticated, CodexNotFound, CodexNotAuthenticated, CursorNotFound, ApiKeyMissing, CodexCliModelRequiresApiKey
3	计费/API	CreditBalanceTooLow, ApiError, ApiResponseError
4	用户取消	UserCancelled
5	I/O	IoError

Config Quick Reference

配置快速参考

Config file:

~/.actualai/actual/config.yaml

(override with

ACTUAL_CONFIG

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
.

配置文件：

~/.actualai/actual/config.yaml

（可通过

ACTUAL_CONFIG

或

ACTUAL_CONFIG_DIR

环境变量覆盖）。

最常用的配置项：

配置项	默认值	用途
`runner`	claude-cli	使用的运行器
`model`	claude-sonnet-4-6	Anthropic运行器使用的模型
`output_format`	claude-md	输出格式：claude-md、agents-md、cursor-rules
`batch_size`	15	每批处理的ADR数量（最小值1）
`concurrency`	10	并行请求数（最小值1）
`invocation_timeout_secs`	600	运行器超时时间（秒，最小值1）
`max_budget_usd`	(无)	支出上限（正数，有限值）

如需全部18个配置项及验证规则，请查看
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
.

格式	文件	头部
claude-md（默认）	`CLAUDE.md`	`# Project Guidelines`
agents-md	`AGENTS.md`	`# Project Guidelines`
cursor-rules	`.cursor/rules/actual-policies.mdc`	YAML前置内容 ( `alwaysApply: true` )

托管区域使用标记：

<!-- managed:actual-start -->

<!-- managed:actual-end -->

。

合并行为：

新根文件：头部 + 托管区域
新子目录文件：仅托管区域（无头部）
已有标记的文件：替换标记之间的内容，保留周围内容
无标记的已有文件：追加托管区域

如需完整格式详情及合并内部逻辑，请查看
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

仅当需要特定主题的详细信息时，才加载以下文件：

文件	加载时机
`references/sync-workflow.md`	排查同步失败问题、了解同步内部流程
`references/runner-guide.md`	设置运行器、模型兼容性、运行器特定行为
`references/error-catalog.md`	排查特定错误，获取完整诊断步骤
`references/config-reference.md`	查看配置项、验证规则、点路径语法
`references/output-formats.md`	输出格式相关问题、托管区域行为、合并逻辑

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

如果本技能或其参考文件未涵盖相关内容，请获取完整的CLI文档：

完整文档（Markdown）：https://cli.actual.ai/docs.md —— 完整的命令参考、所有参数、运行器、输出格式、配置项及故障排查
LLM摘要：https://cli.actual.ai/llms.txt —— 简洁的机器可读概述