cc-safety-net。使用 npx cc-safety-net 或 bunx cc-safety-net 来运行它。
强制执行发生在您的代理内部，通过 cc-safety-net install 配置的插件、扩展或钩子。CLI 本身不需要全局安装 — npx/bunx 会按需获取它来运行此处记录的命令。
本页是命令接口参考，包括命令、子命令、选项和退出行为。它不是教程：有关引导式首次运行，请参阅快速入门；有关各智能体的设置，请参阅安装。
命令概览
CLI 注册了十一个命令。这是它们在cc-safety-net --help 中出现的顺序。
doctor 也接受别名 --doctor。命令查找不区分大小写。
status 和 statusline 是两个不同的命令。status 为人类打印多行报告；statusline 为状态栏打印正好一行的表情符号指示器。status
status 回答一个问题：运行时当前正在强制执行什么？这是在信任它之前确认保护是否生效的最快方法。
裁决
头条裁决是以下两个值之一：
已禁用的 Claude Code 插件不再是其自身的裁决。它被报告为
Not active 列表中的第一个项目符号，作用域限定在该集成上：
~/.claude/settings.json 缺失、解析失败、没有 enabledPlugins，或者没有将 cc-safety-net@cc-marketplace 设置为 true 时，该插件就被视为已禁用 — 检查默认设置为禁用，因此无法读取的设置文件被读取为禁用而不是启用。
裁决来自策略快照，从不从您的配置中重新派生；插件检查仅添加该项目符号，从不更改裁决。
输出
status 打印一个裁决行、一个对齐的事实块，然后是确认或问题列表。
事实行是单行的：长值用
… 截断而不是换行。
事实块之后，status 打印 Everything configured is active. 或一个 Not active 部分，其中包含一个项目符号（当适用时，插件禁用的项目符号在前，然后是快照诊断），后跟 Full report: cc-safety-net doctor。
当 NO_COLOR 设置为环境变量或 stdout 不是 TTY 时，输出会降级为 ASCII：ok/OFF 而不是勾号和叉号图形，- 而不是 ·，并且没有盾牌前缀。
退出码
status 始终退出 0，包括在裁决为 degraded 时。它纯粹是信息性的，因此从不使脚本失败。当您希望在出现问题时获得非零退出码时，请使用 doctor。doctor
doctor 运行完整的安装和配置健康检查，并打印一个分节的报告。
选项：
doctor 在检测到失败时以非零代码退出。失败包括未配置代理、钩子检查失败、自检失败或无效的用户或项目配置。
当某些审计日志文件无法读取时，Recent Activity 部分以 Warning: <n> audit log sources could not be read; this summary is incomplete（当只有一个时为 source）结尾，因此不会将一个安静的星期误认为是完整的。
logs
logs 读取审计日志：每个允许或阻止的命令决策对应一条记录。
logs 打印过去 30 天内每个项目的 20 条最近的拒绝记录。传递 --all 以包含允许的决策。
过滤器和选项
--suspect 将结果缩小到值得再次查看的拒绝记录：带有 failureStage 的拒绝（分析失败且保护器关闭，因此命令从未被证明是危险的），或在同一会话中被拒绝两次或更多次的相同命令签名。重复项在 --since 窗口内计算，然后由 --limit 截断输出。
互斥组合。 两者都会被拒绝并显示明确的消息和退出码 1：
--id不能与--agent、--rule、--session、--project、--suspect、--since或--limit组合使用。--prune-legacy不能与--id、--agent、--rule、--session、--project、--suspect、--all、--since或--limit组合使用。--json和--dry-run是唯一允许与之一起使用的标志。
--dry-run 也会被拒绝：它会打印 --dry-run requires --prune-legacy 并退出 1。
未识别的选项会打印 Unknown option for logs: <arg> 并退出 1。
当审计日志文件无法读取或记录格式错误时，logs 会向 stderr 打印一条警告 — warning: <n> audit log sources could not be read; these results are incomplete（当只有一个时为 source） — 并保持 stdout 和退出码不变。
机器可读输出
人类可读输出为每个条目打印一行 — ID、时间戳、决策、代理、规则 ID 和截断到 50 个字符的命令，
↳ 标记了与完整命令不同的部分。--id 则打印一个标记的详细信息块，涵盖记录的每个字段。
logs —prune-legacy
嵌套的每个项目审计日志永远不会被触及，命令稍后会说明这一点。当所有删除都成功时，它退出0，如果任何文件无法删除，则退出 1。再次运行时，如果没有任何东西需要删除，则是一个空操作。
使用 --dry-run 时，不会删除任何内容。命令打印 Would remove <n> legacy audit log files (<size>). — 或 No legacy audit log files found. — 然后是 Nested v2 audit logs are not included.，并且当有东西要删除时，会打印 Run the same command without --dry-run to delete them.。它始终退出 0。使用 --json 时，它会打印紧凑对象 {"dryRun":true,"files":n,"bytes":n}。
有关旧版布局和当前布局之间的区别，请参阅审计日志。
explain
explain 逐步追踪 CC Safety Net 如何分析命令。使用它来理解命令为何被阻止或允许，或者自定义规则如何适用。
-- 结束标志解析；之后的所有内容都是命令。单个剩余参数按原样使用，因此 shell 操作符会保留；多个参数会被重新引用。
示例：
explain 对阻止和允许的结果都退出 0。请阅读 result 字段而不是退出码。只有选项验证会失败：
- 未知选项会打印
Unknown option for explain: <arg>；没有值的--cwd会打印--cwd requires a value。任何解析错误后都会跟着Usage: cc-safety-net explain [--json] [--cwd <path>] <command>和Pass -- before a command that starts with dashes.，并退出1。 - 不存在的
--cwd路径会打印Error: --cwd path does not exist: <path>并退出1。 - 空命令会打印
Error: No command provided以及用法行，并退出1。
--：它在第一个 -- 处停止查找 --help 和 --version，因此 explain -- --help 会解释字面命令 --help 而不是打印帮助。
有关 --json 返回的 JSON schema，包括 ExplainResult 字段和每个 TraceStep 变体，请参阅 Explain 跟踪参考。
rule
rule 管理你的规则配置、规则簿源和透明命令包装器。本节说明命令接口；规则簿 schema、生命周期和覆盖语义位于自定义规则。
运行不带子命令的 rule 会打印帮助并退出 1。rule --help 打印相同的帮助并退出 0。
选项：
rule init
为当前范围创建规则配置。如果文件存在，命令会将其重写为规范格式，并保留rules、overrides 和 transparent_wrappers。命令在需要时创建规则库缓存目录。
rule init 会写入一个惰性配置，其中不包含任何规则。传递 --example 还会写入一个名为 example-rules 的入门规则库：
example-rules/rulebook.json 不存在时才写入示例规则库。由于配置未引用它，因此它是非活动的。使用 rule add example-rules 添加它以使其活动。
rule add
添加一个规则库源并同步。<source> 是一个裸本地名称（例如 project-rules）或 GitHub 源，形式为 owner/repo#ref/<rulebook-name>：
rule remove
移除一个规则库源并同步。添加--delete-source 以在删除干净的本地源目录时也删除它：
rule update
刷新已配置规则库源的锁定和缓存，或者在提供单个源时刷新该源：rule update 等同于 rule sync。
rule sync
为所有已配置的规则库源重建锁定和缓存。在手动编辑rule.json 后运行它：
--check 时，update 和 sync 都打印 Rule config checked. 而不是 Rule config synced.，并保持锁定和缓存状态不变。
rule list
列出用户范围和项目范围内的活动规则库及其解析的源：rule list 同时读取两个范围，因此拒绝 --global。它仅在策略错误时退出 1；警告会被打印但退出 0。
rule wrapper
管理透明命令包装器 — 这些命令将其参数传递给另一个命令，因此 CC Safety Net 应该分析其内部内容而不是包装器本身。- 操作是必需的，并且必须是
add、remove或list。 wrapper list不接受其他参数。它打印Transparent wrappers: (none)或一个编号列表。wrapper add和wrapper remove各自需要一个命令名。- 包装器名称必须匹配
^[a-zA-Z][a-zA-Z0-9_-]*$，并且保留命令不能注册为包装器。 add会去重；remove会过滤。范围遵循-g/--global。
transparent-wrapper 步骤。
rule verify
验证两个范围内的规则配置文件，包括旧版路径和模式类型检测。在手动编辑配置后使用它：0，无效时退出非零。
rule verify 不是纯粹的检查 — 它可能会修改它验证的文件。当某个范围的 rule.json 验证干净但没有 $schema 键时，命令会重写该文件：它插入
Added $schema to user config. 或 Added $schema to project config.。这仅发生在用户或项目范围内的有效规则模式配置上 — 从不用于旧版配置或有错误的配置 — 并且没有标志可以关闭它。重写会将整个文件重新序列化为两空格缩进，因此在 CI 中，该命令可能会修改已跟踪的文件。如果您需要 rule verify 为只读，请提前提交 $schema 键。
rule migrate
将旧版内联配置文件 — 项目的.safety-net.json 和用户的 ~/.cc-safety-net/config.json — 转换为规则库布局：
--cleanup 在迁移的规则验证后删除旧版文件。migrate 拒绝 --global、--check 和任何第二个位置参数。
rule doc
将规则库编写指南打印到 stdout。将指南通过管道传输到代理以进行规则库编写或验证：rule doc 会检查 npm 注册表是否有更新版本 — 最多每 24 小时一次，结果缓存在 ~/.cc-safety-net/update-check.json 中。当存在更新版本时，它会在 stderr 中写入正好一行：
CC_SAFETY_NET_NO_UPDATE_CHECK 可完全禁用检查。注册表检查失败时是静默的，无论如何退出码都保持 0。
install
install 将 CC Safety Net 集成到代码代理 CLI 中。目标集来自 CC Safety Net 的集成目录，因此与 GUI 和 doctor 使用的列表相同。
有关各智能体的步骤、安装后操作和旧版插件标识符迁移，请参阅安装。
目标
接受十二个目标，按安装顺序排列：安装机制
CC Safety Net 使用三种安装机制：- 原生插件或扩展命令 — Claude Code, Codex, GitHub Copilot CLI, Gemini CLI, OpenClaw, OpenCode, 和 Pi。CC Safety Net 调用代理自带的插件管理器并在此过程中清理被取代的插件 ID。OpenClaw 的安装还会事后验证 OpenClaw 是否报告插件已加载，然后要求您重新启动 OpenClaw Gateway。
- 配置文件写入 — Antigravity CLI, Cursor, 和 Kimi Code。这三个是 CC Safety Net 直接编辑的唯一代理配置。
- 托管插件产物 — Amp Code 和 Hermes Agent。Amp 的插件通过 amp CLI 发布到您账户托管的 Amp Personal Plugins 仓库（预检命令是
amp plugins repositories --json），因此安装需要 amp CLI 和amp login；发布后的插件适用于每个 Amp 会话，包括 Orb 线程。遗留在~/.config/amp/plugins/cc-safety-net.ts的托管本地副本会遮蔽个人插件，因此安装会将其移除。更改后，重启 Amp 或运行plugins: reload。对于 Hermes Agent，安装将插件写入磁盘并运行hermes plugins enable，更改需要重启 Hermes。
npx 缓存中的过时副本。npm 缓存的 _npx 目录下，每个 node_modules 包含 cc-safety-net 的条目都会被移除。缓存路径为 $npm_config_cache（如果已设置）；否则在 macOS 和 Linux 上为 ~/.npm，在 Windows 上为 %LOCALAPPDATA%\npm-cache。这四个集成通过 npx 运行 hook，因此新安装的 hook 会解析到最新版本，而不是缓存版本。
Kimi Code 有两种安装方式。 在终端中，install --kimi-code — 或在选择器中选中 Kimi Code — 会打开一个单选提示：现在安装全局 hook，或改为打印原生 Kimi 插件的步骤（在 Kimi Code 内运行 /plugins install https://github.com/kenryu42/cc-safety-net — 信任提示默认是取消 — 然后运行 /reload 或开始新会话）。选择插件方式不会写入任何内容，只打印步骤。非交互式会话会跳过该提示，直接安装全局 hook。由于该提示是获得插件步骤的唯一途径，即使全局 hook 已配置，安装时 Kimi Code 的行仍然可选，并标记为 (global hook installed)。
选择目标
- 无标志，交互式终端： 会出现一个箭头键多选提示。每个目标都会被探测可用性，因此未安装的代理会显示
CLI not installed，已设置的代理会显示already installed，卸载时未配置的代理会显示not installed。在 Windows 上，探测和安装本身都会通过 shell 解析 npm 的.cmdshim，因此用 npm 安装的 CLI 能被正常检测到，而不会显示CLI not installed。 - 带目标标志： 提供仅一个目标标志。多个标志会引发
Choose exactly one install|uninstall target:并显示完整的标志列表。未知的-参数和多余的位置参数也是错误。
Space 切换高亮目标，Enter 确认（未选择任何内容时只会发出终端铃声），Up/Down — 或 k/j — 在可选择的行之间移动。在安装过程中按 u（或 U）会离开选择器并运行 update 流程，而不是继续安装；卸载页脚省略了该绑定。按 q 或 Esc 退出会打印 Cancelled: nothing was installed.（或 Cancelled: nothing was uninstalled.）并退出 0 — 退出是一个决定，而不是失败。按 Ctrl-C 则会引发 SIGINT，因此进程会像中断的程序一样正常结束。
选定的目标始终按目录安装顺序运行，而不是您选择的顺序。在终端中，每个目标在一个加载指示器后面运行 — Installing <name> integration… 或 Uninstalling <name> integration… — 指示器停止后打印该目标的报告；没有 TTY 时则没有加载指示器。宿主 CLI 的命令在 120 秒后仍未完成会被终止并报告为失败。失败会退出 1 并显示特定于错误的提示 — 权限问题、缺失路径或不是目录的路径组件。
update
update 就地刷新所有已安装的集成。它从不安装任何新内容 — 您尚未设置的代理将保持不变。
amp plugins list 的输出获得资格 — 该输出与 codex plugin list 一样以 30 秒超时获取，因为冷启动会通过网络刷新签出，可能超过默认的 5 秒。GitHub Copilot CLI 是例外 — 它仅在 Copilot 的 installed-plugins 目录中存在 CC Safety Net 插件签出时才有资格，因为其禁用状态与未安装任何东西的开关无法区分，并且更新绝不能变成安装。仍然使用改名前的 safety-net@cc-marketplace 插件 ID 的安装 — 在 Claude Code、Codex 中，或在 GitHub Copilot CLI 中表现为插件签出 cc-marketplace/safety-net — 也会被拾取：更新会将它们迁移到当前 ID，并尽力移除旧版副本，旧版副本移除失败只会发出警告，不会使该目标失败。
每个目标然后按目录安装顺序运行与 install 相同的操作，消息改为 Updated … 或 … up to date。对于那些安装驱动代理自带 CLI 的目标 — Claude Code, Codex, GitHub Copilot CLI, Gemini CLI, Hermes Agent, OpenClaw, OpenCode, 和 Pi — 首先会探测供应商二进制文件：缺失的二进制文件会打印 <Agent> not found; skipped（例如 Codex not found; skipped）并继续运行。配置文件目标 — Antigravity CLI, Cursor, 和 Kimi Code — 不需要二进制文件，并且总是刷新。Amp Code 不需要单独的探测：仅当 amp plugins list 显示个人插件时才会被检测到，其刷新会驱动 amp CLI 发布当前产物。在 Claude Code、Codex 和 GitHub Copilot CLI 上，已注册的市场会在插件步骤之前先刷新（例如 claude plugin marketplace update cc-marketplace），而不是依赖无操作的 add，因此过时的目录签出不会使更新失败。
当没有任何目标符合条件时，update 打印 No installed integrations found. Run `cc-safety-net install` to set one up. 并退出 0。
update 不接受目标标志和参数 — 仅接受 -h/--help。任何其他选项都会打印 Unknown option for update: <flag>，位置参数会打印 Unexpected argument for update: <arg>，两者都会退出 1。一个目标的失败不会停止运行：它的错误会以与 install 相同的提示打印，update 继续处理其余目标，若有任何目标失败，命令在最后退出 1 — 否则退出 0。
您也可以通过交互式 install 选择器按 u 键访问更新流程。
uninstall
uninstall 接受与 install 相同的十二个目标标志，并使用相同的选择规则和目标顺序。
hook
hook 将 CC Safety Net 作为代理的运行时钩子运行。它从 stdin 读取代理的钩子输入作为 JSON，并发出该代理的拒绝格式。您通常不手动运行它：您的代理的插件或配置会将其连接起来。它是保护命令的幕后推手。
hook 需要仅一个集成标志。零个标志 — 或多个标志 — 会打印 hook requires exactly one integration flag. Try: cc-safety-net hook --kimi-code，显示命令帮助，并退出 1。
Amp Code、Codex、OpenClaw、OpenCode 和 Pi 没有自己的
hook 标志。Amp Code、OpenClaw、OpenCode 和 Pi 将 CC Safety Net 作为插件或扩展加载到进程中；Codex 插件调用上面的共享 hook --coding-cli 入口点。有关每个智能体的连接方式，请参阅集成架构。
Antigravity CLI 入口点
install --agy-cli 将命令 npx -y cc-safety-net hook --agy-cli 写入 ~/.gemini/config/hooks.json — Antigravity 共享 .gemini 目录。托管条目名为 cc-safety-net，并注册一个带有 30 秒超时的 PreToolUse 命令钩子。安装在文件不存在时创建它，重新启用已禁用的托管条目，或追加新条目；卸载仅移除命令与托管字符串匹配的条目。
运行时，钩子读取 Antigravity 的 run_command 工具调用，从 conversationId 获取会话 ID，并以 { "decision": "deny", "reason": … } 的形式拒绝。
Cursor 入口点
install --cursor 将命令 npx -y cc-safety-net hook --cursor 写入 ~/.cursor/hooks.json 的 hooks.preToolUse 下，在一个 "version": 1 文档中，带有 30 秒超时和 failClosed: true。安装程序会验证文档的版本和形状，并以描述性错误失败，而不是重写它不识别的内容。重复的托管条目会被合并为一个。
运行时，钩子读取 Cursor 的 Shell 工具调用，从 conversation_id 获取会话 ID，并以 { "permission": "deny", … } 或 { "permission": "allow" } 回答。Cursor 的 working_directory 字段会与工作区根目录进行包含检查，并在缺失但已声明或指向外部时关闭失败。
gui
gui 启动本地策略编辑器，并在你的浏览器中打开它。有关仪表板视图和确认行为，请参阅仪表板。
选项
--no-open 是 gui 接受的唯一参数。任何其他参数都会打印错误 — 选项为 Unknown option for gui: <arg>，位置参数为 Unexpected argument for gui: <arg> — 然后是 Usage: cc-safety-net gui [--no-open]，并退出 1。
服务器始终首先启动，并且 URL 始终打印为 CC Safety Net policy GUI: <url>，无论是否使用该标志 — --no-open 仅抑制浏览器启动。浏览器启动失败不是致命的：gui 会打印手动打开的 URL，服务器会继续运行。
服务器绑定 127.0.0.1 在一个临时端口上，并且每次运行时都会生成一个新的令牌，因此 URL 看起来像 http://127.0.0.1:<port>/?token=<token>。每个请求都必须携带该令牌，并且写入还必须将其作为标头发送。然后进程一直运行直到您中断它。
statusline
statusline 将 CC Safety Net 的当前状态打印为一行表情符号指示器，适合代理状态栏。它需要 --claude-code（短形式 -cc）；没有它，命令会出错，显示帮助，并退出 1。
🛡️ CC Safety Net ❌。否则，它会显示级别的表情符号 — ✅ 标准，🔒 严格，👁️ 偏执，🔧 自定义 — 加上工作树松弛激活时的 🌳，以及策略快照降级时的尾随 ⚠️。
statusline 在输入被管道传输到它时读取标准输入。它会丢弃 Claude Code 的 JSON 状态负载。它会保留其他管道文本并将其作为 <stdin> | <status> 前缀。
statusline 和 status 使用相同的策略快照和环境模式。它们的输出格式不同。使用 status 进行终端报告。使用 statusline 进行程序或状态栏。
有关设置说明和每个指示器的含义，请参阅状态行配置页面。
全局选项
随时检查已安装的版本或获取用法信息。--version 有一个 -V 短别名，--help 有一个 -h 短别名。
help <command> 或 <command> --help 查看特定命令的用法：
Unknown command: <name> — 或以 - 开头的命令打印 Unknown option: <name> — 后跟 Run 'cc-safety-net --help' for usage.，并退出 1。对于未知命令的 help <name> 会打印 Unknown command: <name> 和 Run 'cc-safety-net --help' for available commands.。所有这些失败路径消息，包括它们显示的帮助文本，都会输出到 stderr。