参考
CLI 参考
Apothem CLI 参考——全部子命令与标志。
apothem CLI 是用于管理共享配置档案与工具适配器的主要操作者接口。
全局标志
| 标志 | 说明 |
|---|---|
--version | 打印 Apothem 版本并退出 |
--help | 打印该命令的帮助 |
子命令
apothem install
从共享配置档案安装某个工具适配器。
apothem install --harness <name|all> [--profile PATH] [--project PATH] [--dry-run] [--clean|--fresh] [--yes]| 选项 | 说明 |
|---|---|
--harness <name> | 工具适配器名称（见下方的规范取值）。必填。 |
--profile PATH | 共享配置档案 YAML 的路径。默认为 ~/.config/apothem/profile.yaml。 |
--project PATH | 项目作用域工具的项目根目录。 |
--dry-run | 预览安装而不写入文件。 |
--clean, --fresh | 需主动选择的全新状态：在安装之前，备份并移除先前的安装状态（~/.claude、~/.codex、~/.agents、~/.config/apothem）。 |
--yes | 在全新状态的移除阶段跳过逐目标确认（非交互式 --clean 运行时必填）。 |
规范的 --harness 取值：
antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zed使用 --harness all --project <path> 来选择整个注册表范围的集合。在安装/更新的批量选择期间，会遵循配置档案的 exclude_harnesses 列表。
apothem update
依据当前共享配置档案重新派生某个工具适配器的原生配置。
apothem update --harness <name|all> [--profile PATH] [--project PATH] [--dry-run]| 选项 | 说明 |
|---|---|
--harness <name> | 工具适配器名称。必填。 |
--profile PATH | 共享配置档案 YAML 的路径。 |
--project PATH | 项目作用域工具的项目根目录。 |
--dry-run | 预览更新而不写入文件。 |
update 会重新物化工具的输出。它不会升级 Apothem 引擎本身；请通过安装引擎时所用的渠道（/plugin 流程、npx，或安装与更新脚本）更新引擎，具体见更新。
apothem uninstall
移除某个工具适配器的原生配置。
apothem uninstall --harness <name|all> [--project PATH] [--yes]| 选项 | 说明 |
|---|---|
--harness <name> | 工具适配器名称。必填。 |
--project PATH | 项目作用域工具的项目根目录。 |
--yes | 跳过确认提示。 |
apothem verify
验证某个工具适配器的受管目标存在且有效。
apothem verify --harness <name|all> [--profile PATH] [--project PATH]| 选项 | 说明 |
|---|---|
--harness <name> | 工具适配器名称或 all。必填。 |
--profile PATH | 用于检查保真度的共享配置档案 YAML。未提供时，该检查纯粹是结构性的。 |
--project PATH | 项目作用域工具的项目根目录。 |
未提供 --profile 时，该检查是结构性的：每个受管目标都必须存在且有效。提供 --profile 时，它还要求保真度，因此一个存在但已偏离该配置档案的安装无法通过验证——用它来确认某个特定的配置档案已被忠实安装。
当工具通过验证（并且在提供 --profile 时忠实于该配置档案）时，退出码为 0；当某个目标缺失或无效时，或者当提供了 --profile 且安装已漂移时，退出码为 1。
apothem status
报告每个已注册工具的安装、验证和漂移状态。
apothem status [--profile PATH] [--project PATH]| 选项 | 说明 |
|---|---|
--profile PATH | 用作漂移基线的共享配置档案。无法读取的默认配置档案会使漂移降级为 unknown，而不是中止整个扫查。 |
--project PATH | 项目作用域工具的项目根目录。未提供时，这些工具报告 needs-project。 |
每一行都将一个 installed 标志与一个 verified 标志配对，两者组合成漂移状态：
| 状态 | 含义 |
|---|---|
absent | Apothem 尚未安装到此工具中。 |
in-sync | 已安装，且与配置档案基线一致。 |
drift | 已安装，但已不再一致——使用 apothem update 进行修复。 |
unknown | 已安装，但无法读取基线配置档案。 |
needs-project | 报告某个项目作用域工具时未提供 --project，因此无法解析其目标。 |
installed 回答的是“Apothem 是否在此处安装过？”，而不是“此工具是否存在于这台机器上？”。它以 Apothem 自己的工件为依据——指令锚点内的受管区块，以及 Apothem 自有的 .apothem/ 子树下的内容——绝不以工具为自身写入的、归厂商所有的文件为依据。一个配置目录存在但 Apothem 从未触及过的工具会报告 absent；一个已被卸载的工具即使其已清空的目录仍然存在，也会报告 absent。
apothem profile
管理共享的 Apothem 配置档案。
apothem profile show [--profile PATH]
apothem profile init [--profile PATH] [--force]
apothem profile set <key> <value> [--profile PATH]
apothem profile edit [--profile PATH]| 子命令 | 说明 |
|---|---|
profile init | 创建一个符合 schema 的最小配置档案脚手架。 |
profile show | 将解析后的配置档案以 JSON 打印到 stdout。使用 --json 时，文档以 schema_version 开头。 |
profile set <key> <value> | 设置一个配置档案字段。该值以字面字符串存储——裸词不会被强制转换，因此 no 仍为 "no"，1.0 仍为字符串——但 true/false 以及显式的 [...] / {...} 列表与映射输入除外。组装后的配置档案在写入之前会经过 schema 校验。 |
profile edit | 在 $EDITOR 中打开配置档案（回退到平台默认编辑器）。 |
--profile PATH 选项可让每个子命令指向另一个配置档案文件。默认为 ~/.config/apothem/profile.yaml。
apothem harnesses
列出并检视已注册的工具适配器。
apothem harnesses list
apothem harnesses show <name>| 子命令 | 说明 |
|---|---|
harnesses list | 打印一张表格，列出每个已注册的适配器及其安装状态标志与输出路径。 |
harnesses show <name> | 打印某个适配器的名称、安装状态与输出路径。 |
apothem doctor
为 Apothem 安装运行系统诊断。
apothem doctor打印 Apothem 版本、Python 解释器、平台、解析得到的配置档案路径，以及按工具划分的安装状态表。当任一检查失败时，退出码为 1：包括配置档案无效、已安装的工具无法通过验证、已注册的钩子命令无法启动、适配器无法加载或无法探测，或账本不可读。未安装的工具会被报告，但不算失败；提示性说明不会改变退出码。
生成的命令与标志参考
| Command | Flags | Description |
|---|---|---|
apothem backups prune | --dry-run, --format, --harness, --json, --keep, --no-color, --quiet, -q, --verbose, -v | Delete backup sets and install records beyond the newest N per harness. Keeps the newest N backup sets under ~/.apothem/backups/ for each selected harness, and the newest N install records per install root in its ledger under ~/.apothem/state/. A backup set that a kept record, or the latest install record of any install root, still references is never deleted, so rollback of the latest install still restores. |
apothem completion | — | Print a shell-completion script for SHELL to stdout. Supported shells: bash, zsh, fish, powershell. Every script is generated by Click's env-var completion protocol — PowerShell through the completion class registered above, since Click ships none natively. Enabling completion is opt-in: this command only prints the script — pipe or append it to the shell's completion file yourself (see --help). |
apothem diff | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Preview the pending configuration changes for a single harness. |
apothem doctor | --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Check the installed harnesses and the shared profile; exit 1 on any failure. Reports the engine version, Python, and platform; validates a present shared profile against the packaged schema; and, for every installed harness, runs the adapter's verify and starts each hook command the install registered with a no-op payload. A harness that is not installed is reported but is not a failure, so a machine with one healthy harness passes. Project-scope harnesses are checked when --project names their root. |
apothem harnesses list | --format, --json, --no-color, --quiet, -q, --verbose, -v | List all registered harness adapters. |
apothem harnesses show | --format, --json, --no-color, --quiet, -q, --verbose, -v | Show details for a specific harness adapter. |
apothem install | --clean, --fresh, --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Install a harness adapter configuration. |
apothem migrate-workspace | --dry-run, --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Migrate a legacy per-harness workspace into the shared .apothem layout. The base is the resolved --project root when supplied, otherwise the current working directory (the project-local default). Per-harness memory/contexts/learning stores union-merge into the shared store; a conflicting record is skipped, never overwritten; a legacy .plans tree moves under .apothem/plans; every consumed source is backed up first. The migration is idempotent. |
apothem profile edit | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Open the shared profile in the system editor. |
apothem profile init | --force, --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Create a schema-valid shared profile scaffold. |
apothem profile set | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Set a key in the shared profile. KEY is a dotted path that descends into the nested profile structure (identity.name, preferences.style, enforcement.sprints, harnesses.<harness>.preferences.style); a single key with no dot sets a top-level node. VALUE is stored as a literal string — bare words are not coerced (no stays "no", 2024-01-01 and 1.0 stay strings) — except true/false (the boolean enforcement flags) and explicit [...]/{...} list/map input. The fully-assembled profile is validated against the packaged schema BEFORE writing; an invalid set is refused with the standard diagnostic and the profile on disk is unchanged. |
apothem profile show | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Display the current shared profile. |
apothem quickstart | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Guided first run: ensure a profile, preview the writes, then install. Walks a new operator through the canonical path in one linear flow — create a starter profile if none exists (with a personalize nudge), preview the files each harness will write (project root vs your home directory), confirm, then install with the grouped capability-note output — and ends with the recommended next commands. --yes runs the whole sequence non-interactively; --format json emits one structured summary of every step. It composes the install building blocks; it does not duplicate them. Without --harness it asks which harness to install, so the first run writes one harness's configuration rather than all of them; all is an explicit choice. A run that cannot ask fails with a usage error before anything is written. |
apothem rollback | --format, --harness, --install-id, --json, --last, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Restore a harness to the state before its recorded install. |
apothem status | --format, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Report install, verify, and drift state for every registered harness. |
apothem uninstall | --format, --harness, --json, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Remove a harness adapter configuration. |
apothem update | --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Re-install a harness adapter configuration from the current profile. |
apothem verify | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Verify a harness adapter installation. Without --profile the check is structural: every managed target must be present and valid. With --profile the check additionally requires profile fidelity, so a present-but-drifted install fails verify — answering "is THIS profile faithfully installed?" rather than merely "does it exist?". |