CC Safety Net provides CLI commands for diagnostics, command analysis, status line output, hook installation, and rulebook management. Run them with npx cc-safety-net or bunx cc-safety-net.
CC Safety Net is invoked through your agent; there is no global install step. npx/bunx are only used to run the CLI subcommands documented here.
doctor
The doctor command runs a full health check of your CC Safety Net installation and prints a summary of what it finds.
npx cc-safety-net doctor
bunx cc-safety-net doctor
| Check | Description |
|---|
| Hook Integration | Verifies the plugin/hook is configured for each supported agent: Claude Code, Codex, Copilot CLI, Gemini CLI, Kimi Code, OpenCode, and Pi |
| Self-Test | Runs sample commands to confirm blocking works (git reset --hard and rm -rf / blocked; rm -rf ./node_modules allowed) |
| Configuration | Validates custom rules in user and project configs |
| Environment | Shows status of mode flags (CC_SAFETY_NET_STRICT, CC_SAFETY_NET_PARANOID, etc.; legacy SAFETY_NET_* also listed when set) |
| Recent Activity | Summarizes blocked commands from the last 7 days |
| System Info | Displays versions of all relevant tools |
| Update Check | Checks if a newer version is available |
| Flag | Description |
|---|
--json | Output in JSON format (useful for sharing in bug reports) |
--skip-update-check | Skip the npm version check |
explain
The explain command traces how CC Safety Net analyzes a command step-by-step. Use it to debug why a command is blocked or allowed, or to understand how a custom rule applies.
npx cc-safety-net explain "git reset --hard"
bunx cc-safety-net explain "git reset --hard"
| Flag | Description |
|---|
--json | Output the analysis as JSON |
--cwd <path> | Use a custom working directory for analysis |
npx cc-safety-net explain "rm -rf /"
npx cc-safety-net explain --json "git checkout -- file.txt"
npx cc-safety-net explain --cwd /tmp "git status"
--json (the ExplainResult fields and every TraceStep variant), see the Explain trace reference.
statusline
The statusline command outputs CC Safety Net’s current status in a format suitable for Claude Code’s status line. It shows whether the Claude Code plugin is enabled and which modes are active. This command is Claude-Code-specific — it requires --claude-code.
bunx cc-safety-net statusline --claude-code
# -cc is a short alias for --claude-code
bunx cc-safety-net statusline -cc
hook
The hook command has two roles: installing/uninstalling the hook for agents that need a config write, and running as the runtime PreToolUse hook invoked from an agent’s config.
hook install / hook uninstall
Write or remove CC Safety Net’s hook in an agent’s config file. Currently the only supported target is Kimi Code, whose config is the only one CC Safety Net writes directly. All other agents are installed through their own plugin or extension marketplaces — see Installation.
# Install the Kimi Code hook
npx -y cc-safety-net hook install --kimi-code
# Remove the Kimi Code hook
npx -y cc-safety-net hook uninstall --kimi-code
--kimi-code is the only install/uninstall target. This writes a [[hooks]] block to ~/.kimi-code/config.toml (or $KIMI_CODE_HOME/config.toml).
Runtime hook entrypoints
When CC Safety Net runs as an agent’s PreToolUse hook, the agent invokes cc-safety-net hook <flag>. These entrypoints read the agent’s hook input from stdin and emit the agent-specific deny format. You normally do not run these by hand — your agent’s plugin or config wires them up — but they are the actual command behind the protection.
| Flag | Agent | Hook event / tool | Legacy top-level alias |
|---|
--claude-code / -cc | Claude Code | PreToolUse / Bash | Yes (cc-safety-net --claude-code) |
--copilot-cli / -cp | GitHub Copilot CLI | preToolUse / bash | Yes (cc-safety-net --copilot-cli) |
--gemini-cli / -gc | Gemini CLI | BeforeTool / run_shell_command | Yes (cc-safety-net --gemini-cli) |
--kimi-code / -kc | Kimi Code | PreToolUse / Bash | No |
-cc, -cp, and -gc also work as legacy top-level flags (for example cc-safety-net --claude-code); -kc is only valid as hook --kimi-code. Codex, OpenCode, and Pi do not use this command — they load CC Safety Net as a plugin or in-process extension instead. See Integration Architecture for how each agent plugs in.
rule
The rule command manages rulebook-based custom rules. See Custom Rules for the full authoring guide.
Shared flags (apply to most subcommands):
| Flag | Description |
|---|
-g, --global | Use the user-scope rule config (~/.cc-safety-net/rules/rule.json) instead of the project scope |
--check | Check without changing lock/cache state (valid with update and sync) |
--delete-source | Delete the local source directory on remove |
--cleanup | Delete legacy files after migrate verifies them |
-h, --help | Show help |
rule init
Create a starter project rule config and rulebook in the current directory:
npx -y cc-safety-net rule init
--global to create the user-scope config at ~/.cc-safety-net/rules/rule.json instead:
npx -y cc-safety-net rule init --global
rule add
Add a rulebook source and sync. <source> is a bare local name (for example project-rules) or a GitHub source in the form owner/repo#ref/<rulebook-name>:
npx -y cc-safety-net rule add project-rules
npx -y cc-safety-net rule add kenryu42/cc-safety-net#main/block-git-add-all
npx -y cc-safety-net rule add --global my-personal-rules
rule remove
Remove a rulebook source and sync. Use --delete-source to also delete the local source directory:
npx -y cc-safety-net rule remove project-rules
npx -y cc-safety-net rule remove project-rules --delete-source
rule update
Refresh the lock and cache for configured rulebook sources, or a single source if one is given. Use --check to verify without writing:
npx -y cc-safety-net rule update
npx -y cc-safety-net rule update project-rules
npx -y cc-safety-net rule update --check
rule sync
Rebuild the lock and cache for all configured rulebook sources. Run after adding or changing entries in rule.json:
npx -y cc-safety-net rule sync
rule sync is equivalent to rule update with no source argument.
rule list
List the active rulebooks and their resolved sources across user and project scope:
npx -y cc-safety-net rule list
rule test
Run every fixture defined in every active rulebook (or a single source) and confirm rules block and allow as expected:
npx -y cc-safety-net rule test
npx -y cc-safety-net rule test project-rules
rule verify
Validate the structure of all active rulebooks and rule definitions. Use this in CI or whenever you edit a rulebook by hand:
npx -y cc-safety-net rule verify
0 if everything is valid, or non-zero if errors are found.
rule migrate
Convert legacy inline config files (.safety-net.json, ~/.cc-safety-net/config.json) into the new rulebook layout:
npx -y cc-safety-net rule migrate
--cleanup to delete the legacy files after the migrated rules are verified:
npx -y cc-safety-net rule migrate --cleanup
rule doc
Print a machine-readable document describing the rulebook schema. Pipe the output to your agent to let it help author or validate rulebooks interactively:
npx -y cc-safety-net rule doc
Version and help flags
You can check the installed version or get usage information at any time. --version has a -V short alias, and --help has a -h short alias.
npx cc-safety-net --version
npx cc-safety-net -V
npx cc-safety-net --help
npx cc-safety-net -h
help <command> or <command> --help to see usage for a specific subcommand:
npx cc-safety-net help explain
npx cc-safety-net explain --help
npx cc-safety-net help doctor
Last modified on June 22, 2026
