CLI Reference

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

Global options

All commands accept:

clash init

Initialize a new clash policy with a safe default configuration.

clash init [SCOPE] [OPTIONS]

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]

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]...

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

clash policy

clash policy allow / deny / remove

Add or remove rules from your policy.json. Supports positional command syntax or explicit flags.

# Positional syntax — parsed as bin + args
clash policy allow "gh pr create"
clash policy deny "rm -rf"
clash policy remove "gh pr create"

# Explicit flags
clash policy allow --tool Read
clash policy deny --bin curl
clash policy allow --bin cargo --sandbox cwd

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 create / delete / list

Manage named sandbox definitions in your policy.json.

clash sandbox create dev --network allow --doc "Dev sandbox"
clash sandbox delete dev
clash sandbox list [--json]

clash sandbox add-rule / remove-rule

Add or remove filesystem rules within a named sandbox.

clash sandbox add-rule dev ./src --caps read
clash sandbox add-rule dev ./target --caps read,write
clash sandbox remove-rule dev ./target

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]

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:

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

Exit codes

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