CLI Reference
Every subcommand of tool-gates. The binary doubles as the hook entry point (reads tool-call JSON from stdin and emits a decision) and as a management CLI for inspecting and editing your settings.
Hook lifecycle
Install, inspect, audit.
| Command | What it does |
|---|---|
tool-gates hooks add -s user |
Wire all four tool-gates hooks into ~/.claude/settings.json. Use -s project or -s local for project-scoped installs. |
tool-gates hooks add --gemini |
Wire the deprecated Gemini compatibility hook into ~/.gemini/settings.json for an existing setup. New setups should use Antigravity. |
tool-gates hooks add --codex |
Wire PreToolUse, PermissionRequest, PostToolUse into ~/.codex/hooks.json. The installer bakes --client codex into each command so the wire format routes correctly. |
tool-gates hooks add --antigravity |
Wire a single PreToolUse hook into the shared user path at ~/.gemini/config/hooks.json by default. The installer bakes --client antigravity into the command. The -s project scope writes .agents/hooks.json. Antigravity (agy) is Google's successor to the Gemini CLI. |
tool-gates agy allowlist |
Print a native permissions.allow block (one command(<prog>) rule per unconditionally-safe program) for ~/.gemini/antigravity-cli/settings.json. A hook allow cannot suppress an agy prompt, so this native allowlist is what stops prompts for read-only commands. |
tool-gates agy allowlist --apply |
Merge that allowlist into ~/.gemini/antigravity-cli/settings.json (preserves existing entries, backs up first). Add --dry-run to preview. Restart agy afterward so it re-reads settings. |
tool-gates hooks add … --dry-run |
Print what would change without writing. Works on every hooks add variant. |
tool-gates hooks status |
Report which clients have hooks installed and at which scope. Green / red status per hook. |
tool-gates hooks json [--codex|--antigravity|--gemini] |
Emit the canonical hook configuration as JSON (Claude shape by default; pass a client flag for that client's shape). Useful for diffing against an existing settings file. |
Approval learning
Pending queue and rules management.
| Command | What it does |
|---|---|
tool-gates pending list [--project] [--json] | List queued asks across every project by default. --project filters to the current project; --json emits machine-readable output. |
tool-gates pending clear [--project | --all] --force | Empty the selected queue. Requires an explicit scope and --force; cannot be undone. |
tool-gates approve '<pattern>' -s <scope> [--type <type>] [--dry-run] | Write a permission rule into the named settings file. Scope is local, project, or user; type is allow by default and can be ask or deny. |
tool-gates rules list | List every rule currently in any settings file you control. |
tool-gates rules remove '<pattern>' -s <scope> | Remove a specific rule from the named settings file. |
tool-gates rules ask-audit | List permissions.ask rules in settings.json categorised by what tool-gates would do without them (gate-covered, safety floor, indeterminate). |
tool-gates rules ask-audit --apply | Multi-select TUI for removing redundant ask rules. The third "don't ask again" button reappears for everything removed. |
tool-gates rules export --format md [--out PATH] [--rules-dir PATH] | Regenerate gates/*.md, security-floor.md, hints.md, security-reminders.md, and design-lint.md from the rule, hint, and scanner catalogs. --out defaults to docs/src. |
tool-gates review | Open the interactive review TUI to promote, deny, or dismiss pending commands and manage existing rules. --all spans every project; the default is the current project. See Review TUI. |
Diagnostics
Health check, cache, version.
| Command | What it does |
|---|---|
tool-gates doctor | Verify config, hook installation, cache files, and flag legacy bash-gates remnants. More on the doctor page. |
tool-gates --tools-status | Print which modern CLI tools (bat, rg, fd, ast-grep, etc.) are detected on PATH. The hint engine uses this cache. |
tool-gates --refresh-tools | Re-scan the system for modern CLI tools and rewrite ~/.cache/tool-gates/available-tools.json. Run after installing new tools. |
tool-gates --version | Print the version. |
tool-gates --help | Print the top-level help. Each subcommand also accepts --help. |
The CLI surfaces only the safe operations. Mutating subcommands (approve, rules remove, pending clear, hooks add) ask for confirmation through the same gate engine that protects every other tool call. See the tool_gates gate.