CLI Reference

shellfirm

The main command. Without subcommands, it shows usage information.

shellfirm [OPTIONS] <COMMAND>

Global options

Flag	Description
--version	Print version information
--help	Print help information

---

shellfirm init

Set up shell hooks for command interception.

# Auto-detect and install for all shells
shellfirm init --install

# Auto-detect and uninstall from all shells
shellfirm init --uninstall

# Print hook for a specific shell (does not modify any files)
shellfirm init zsh
shellfirm init bash
shellfirm init fish
shellfirm init nushell
shellfirm init powershell
shellfirm init elvish
shellfirm init xonsh
shellfirm init oils

Flag	Description
--install	Detect all installed shells and add hooks to their config files
--uninstall	Remove shellfirm hooks from all configured shells

---

shellfirm pre-command

The internal command called by shell hooks. You do not need to run this directly.

shellfirm pre-command --command "rm -rf /"

Flag	Description
-c, --command	The command string to check

---

shellfirm config

Manage shellfirm configuration. Running config with no subcommand opens an interactive menu.

shellfirm config

config show

Display a human-readable summary of current settings:

shellfirm config show

config challenge

Set the default challenge type:

shellfirm config challenge [Math|Enter|Yes]

Without an argument, shows an interactive select prompt.

config severity

Set the minimum severity threshold:

shellfirm config severity [all|Info|Low|Medium|High|Critical]

Without an argument, shows an interactive select prompt. Use all to clear the threshold (trigger on everything).

config groups

Manage check groups:

shellfirm config groups --enable <group> --disable <group>

Flag	Description
--enable <group>	Enable a check group (repeatable)
--disable <group>	Disable a check group (repeatable)

Without flags, shows an interactive multi-select of all groups.

Examples:

shellfirm config groups --enable aws --disable heroku
shellfirm config groups                # Interactive multi-select

config ignore

Manage ignored pattern IDs (patterns that never trigger):

shellfirm config ignore <pattern-id>
shellfirm config ignore --remove <pattern-id>
shellfirm config ignore --list

Flag	Description
--remove	Remove a pattern from the ignore list
--list	Show all currently ignored patterns

config deny

Manage denied pattern IDs (patterns blocked without a challenge):

shellfirm config deny <pattern-id>
shellfirm config deny --remove <pattern-id>
shellfirm config deny --list

Flag	Description
--remove	Remove a pattern from the deny list
--list	Show all currently denied patterns

config llm

Configure LLM analysis settings:

shellfirm config llm [OPTIONS]

Flag	Description
--provider <provider>	LLM provider (anthropic or openai-compatible)
--model <model>	Model ID
--base-url <url>	Custom API base URL
--timeout <ms>	Request timeout in milliseconds

Without flags, shows interactive prompts for each field.

Examples:

shellfirm config llm --provider anthropic --model claude-sonnet-4-20250514
shellfirm config llm --timeout 10000
shellfirm config llm                   # Interactive prompts

config context

Configure context-aware protection settings (protected branches, production k8s patterns, sensitive paths, escalation levels):

shellfirm config context

Opens an interactive sub-menu for managing context settings.

config edit

Open the settings file in your $EDITOR:

shellfirm config edit

config reset

Reset configuration to defaults:

shellfirm config reset

Prompts you to either overwrite or back up your existing configuration.

---

shellfirm check

Test commands against shellfirm checks or list available checks.

Test a command (dry-run)

shellfirm check --command "rm -rf /"
shellfirm check -c "git push --force origin main"

This runs the command through the check pipeline without presenting a challenge. It shows matched patterns, severity, blast radius, and alternatives.

List active checks

shellfirm check --list
shellfirm check -l

Filter by group

shellfirm check --list --group git
shellfirm check -l -g docker

Include all checks (including disabled groups)

shellfirm check --list --all
shellfirm check -l -a

Flag	Description
-c, --command	Command to test (dry-run)
-l, --list	List all active checks
-g, --group	Filter checks by group (used with --list)
-a, --all	Include checks from disabled groups (used with --list)

---

shellfirm audit

Manage the audit trail.

Show the audit log

shellfirm audit show

Prints the raw JSON-lines audit log. Pipe to jq for formatting:

shellfirm audit show | jq .

Clear the audit log

shellfirm audit clear

---

shellfirm policy

Manage project-level policies.

Initialize a policy

shellfirm policy init

Creates a .shellfirm.yaml template in the current directory.

Validate a policy

shellfirm policy validate

Checks the .shellfirm.yaml in the current directory for syntax errors and reports warnings.

Flag	Description
--path	Path to the policy file (defaults to .shellfirm.yaml in current directory)

---

shellfirm status

Show the current shellfirm status.

shellfirm status

Displays:

• Configuration file path
• Active challenge type
• Severity threshold
• Enabled/disabled groups
• Context detection results
• Audit log status

---

shellfirm mcp

Start the MCP (Model Context Protocol) server for AI agent integration.

shellfirm mcp

Runs a JSON-RPC 2.0 server over stdin/stdout. See Agents & Automation for details.

---

shellfirm wrap

Launch an interactive program inside a PTY proxy with shellfirm protection.

shellfirm wrap [OPTIONS] <COMMAND> [ARGS...]

Flag	Description
-d, --delimiter	Override the statement delimiter (e.g., ; or \n)

Examples:

shellfirm wrap psql -h localhost -U postgres
shellfirm wrap redis-cli
shellfirm wrap --delimiter ';' mysql -u root
shellfirm wrap mongosh mongodb://localhost/mydb

See Interactive Wrapper for details.

---

shellfirm completions

Generate shell completion scripts.

shellfirm completions <SHELL>

Supported shells: bash, zsh, fish, powershell, elvish.

Example:

# Zsh
shellfirm completions zsh > ~/.zfunc/_shellfirm

# Bash
shellfirm completions bash > /etc/bash_completion.d/shellfirm

# Fish
shellfirm completions fish > ~/.config/fish/completions/shellfirm.fish