CLI Reference

Every command, flag, and workflow for the clash binary.

Global options

All commands accept:

Flag	Description
`-v`, `--verbose`	Enable verbose/debug output
`-V`, `--version`	Print version
`-h`, `--help`	Print help

clash init

Initialize a new clash policy with a safe default configuration.

clash init [SCOPE] [OPTIONS]

Argument	Description
`SCOPE`	`user` (global) or `project` (this repo). Omit for interactive prompt.

Flag	Description
`--no-bypass`	Skip setting `bypassPermissions` in Claude Code settings

What it does:

clash init user — Creates ~/.clash/policy.star with a safe default policy, installs the Claude Code plugin, configures Claude Code so clash is the sole permission handler, and installs the status line.
clash init project — Creates .clash/policy.star in the current repo root with a minimal deny-all policy.

clash init              # interactive — prompts you to choose
clash init user         # set up your global policy
clash init project      # create a repo-specific policy

clash status

Show policy status: layers, rules with shadowing, and potential issues.

clash status [OPTIONS]

Flag	Description
`--json`	Output as JSON
`--verbose`	Show all rules including builtins

clash doctor

Diagnose common setup issues and report fix instructions.

clash doctor

Checks: Policy files exist, policy parses successfully, plugin installed, binary on PATH, file permissions, sandbox support.

clash explain

See which rule matches a given tool invocation.

clash explain <TOOL> [ARGS]...

Argument	Description
`<TOOL>`	Tool type: `bash`, `read`, `write`, `edit`, `tool`
`[ARGS]...`	Command, file path, or noun to check

clash explain bash git push origin main
clash explain read .env
clash explain --json bash rm -rf /

clash policy

clash policy show

Show the compiled decision tree.

clash policy show [--json]

clash policy validate

Validate policy files and report errors.

clash policy validate [--file <PATH>] [--json]

clash policy list

List all rules with level tags.

clash policy list

clash sandbox

clash sandbox check

Check if sandboxing is supported on the current platform.

clash sandbox check

clash sandbox exec

Apply sandbox restrictions and execute a command.

clash sandbox exec --sandbox <SANDBOX> --cwd <CWD> [COMMAND]...

clash sandbox exec \
  --sandbox '{"read":["/Users/me/project"],"write":[]}' \
  --cwd /Users/me/project \
  ls -la

clash update

Update clash to the latest release from GitHub.

clash update [OPTIONS]

Flag	Description
`--check`	Only check for updates
`-y`, `--yes`	Skip confirmation
`--version <VERSION>`	Install a specific version

clash bug

File a bug report to the issue tracker.

clash bug <TITLE> [-d <DESCRIPTION>] [--include-config] [--include-logs]

Interactive skills

Once clash is running inside Claude Code, you have access to slash commands for managing your policy without leaving your session:

Skill	What it does
`/clash:onboard`	Interactively build your policy from scratch
`/clash:edit`	Guided editing of your policy file
`/clash:status`	Show current policy and enforcement status
`/clash:describe`	Plain-English description of your active policy
`/clash:explain`	See which rule matches a specific tool invocation
`/clash:allow`	Quickly add an allow rule
`/clash:deny`	Quickly add a deny rule
`/clash:test`	Test your policy against hypothetical tool uses
`/clash:audit`	View recent permission decisions

Disabling clash

Set CLASH_DISABLE to temporarily bypass all enforcement:

CLASH_DISABLE=1 claude    # disable for one session
unset CLASH_DISABLE       # re-enable

Environment variables

Variable	Effect
`CLASH_DISABLE`	Set to `1` to disable all enforcement

Exit codes

Code	Meaning
`0`	Success
`1`	General error (parse failure, I/O error)
`2`	CLI usage error (invalid arguments)

Uninstalling

claude plugin uninstall clash          # remove the plugin
cargo uninstall clash                  # remove the binary (cargo)
rm -f ~/.local/bin/clash               # remove the binary (install script)
# Optional cleanup:
rm -rf ~/.clash                        # user-level policy and logs
rm -rf .clash                          # project-level policy