CLI Reference

Complete reference for all wsh commands. The binary name is wsh (installed via cargo install wsh).

Global options

Flag	Description
`--profile <NAME>`	Use a named profile instead of the default
`--version`	Print version information
`--help`	Print help

wsh setup

Interactive setup for a specific use case. Installs manifests, locks the policy, adds shell aliases, and installs the guard hook.

wsh setup [BUNDLE]

Available bundles:

codex — OpenAI Codex CLI (git, npm, pip, dangerous-patterns, sanitize-env)
claude — Anthropic Claude Code CLI (git, npm, pip, dangerous-patterns, sanitize-env)
minimal — Coreutils and dangerous-pattern blocking only

If no bundle is specified, an interactive menu is shown.

wsh guard

Manage the global shell guard or evaluate a command string against policy.

Global guard mode

Enable or disable global guarding of all shell sessions. By default, only agent-spawned sessions are policy-checked. Use --all to guard every session on the machine (recommended for dedicated agent machines).

wsh guard --all              # enable global guard
wsh guard --off              # disable global guard
wsh guard                    # show current status

--all adds export WSH_GUARD=1 to ~/.zshenv and ~/.bashenv. --off removes it. No lock required — this is a shell environment setting, not a policy change.

Shell hook mode (internal)

When called with a command string argument, evaluates it against policy. Used internally by the .zshenv/.bashenv guard hook. Skips shell builtins, checks external commands, logs to audit. Returns exit code 0 (allow) or 1 (deny).

wsh guard "<COMMAND_STRING>"

wsh exec

Execute a command under warrant enforcement. The command is checked against the signed policy before execution.

wsh exec -- <COMMAND> [ARGS...]

Everything after -- is treated as the command to execute. Hyphen-prefixed arguments are passed through to the target command.

Examples

wsh exec -- git push origin main
wsh exec -- cargo build --release
wsh exec -- curl https://api.example.com

wsh check

Dry-run a command against the policy without executing it. Reports whether the command would be allowed or denied.

wsh check <COMMAND> [ARGS...]

Examples

wsh check git push --force origin main
# Output: denied — capability "git.push_force" not granted

wsh add

Add a tool to your local drafts directory by generating a draft policy from its manifest.

wsh add <NAME> [OPTIONS]

Flag	Description
`--registry <URL>`	Custom registry source (git URL) for the manifest
`--scope <system\|project>`	Draft location scope. Default: `system`

Examples

wsh add git
wsh add git --scope project
wsh add acme-tool --registry git@corp.com:warrants.git

wsh edit

Open a tool's draft policy in your $EDITOR for editing.

wsh edit <NAME> [OPTIONS]

Flag	Description
`--scope <system\|project>`	Which draft to edit. Default: `system`

wsh pull

Fetch manifests from the registry to your local cache. If no name is provided, wsh fetches all manifests.

wsh pull [NAME]

The name can be a simple tool name (e.g. git) or a namespaced ID (e.g. warrant-sh/git, acme-corp/custom-tool).

wsh search

Search for available manifests.

wsh search <QUERY>

wsh lock

Compile draft policies into a signed, enforceable warrant. Requires sudo.

sudo wsh lock [OPTIONS] [TOOL]

Flag	Description
`--draft <PATH>`	Path to a specific draft file to compile
`[TOOL]`	Compile only this tool's rules (optional; compiles all if omitted)

Examples

sudo wsh lock          # compile all drafts
sudo wsh lock git      # compile only git's rules

wsh status

Show the current warrant status — active policy version, covered tools, and enforcement state.

wsh status

wsh audit

View the enforcement audit log.

wsh audit [OPTIONS]

Flag	Description
`--tail <N>`	Number of entries to show. Default: `20`
`--json`	Output as JSON Lines (for piping to jq, etc.)
`--clear`	Clear the audit log

Examples

wsh audit
wsh audit --tail 50
wsh audit --json | jq '.capability'

wsh audit verify

Validate the integrity of the audit ledger's SHA-256 hash chain. Each audit entry includes the hash of its predecessor; this command walks the chain and reports any breaks or tampering.

wsh audit verify

Exits with status 0 if the chain is intact, non-zero if any inconsistency is detected.

wsh elevate

Temporarily bypass warrant enforcement by authenticating as a human. Prompts for the system password.

wsh elevate [OPTIONS]

Flag	Description
`--duration <MINUTES>`	How long to stay elevated. Default: `30`

wsh de-elevate

End elevation early, restoring warrant enforcement immediately.

wsh de-elevate

wsh is-elevated

Check whether the current session is elevated.

wsh is-elevated

Exits with status 0 if elevated, non-zero otherwise. Useful in scripts.

wsh profiles

List available profiles. Profiles let you maintain separate policy configurations (e.g. one for development, one for CI).

wsh profiles

wsh projects

List projects with project-scoped policies.

wsh projects