FAQ

Does shellfirm slow down my shell?

No. The check pipeline typically completes in under 5ms per command. Context detection (git branch, k8s context) adds up to 100ms on first invocation but is fast on subsequent calls. Commands that do not match any pattern pass through with no visible delay.

Can shellfirm be bypassed?

Yes, intentionally. You can bypass the shell hook with:

\command rm -rf /tmp/test

or:

command rm -rf /tmp/test

This is by design. shellfirm is a safety net, not a security tool. It catches mistakes, not malice. If someone wants to bypass it, they can -- but doing so is a deliberate action, not an accident.

Does it work in scripts?

Shell hooks only work in interactive shells. Non-interactive scripts (bash scripts, cron jobs, CI pipelines) do not load shell hooks, so shellfirm does not intercept commands automatically.

For scripts and automation, use:

shellfirm check -- evaluate commands programmatically
shellfirm mcp -- integrate with AI agents via MCP protocol
shellfirm wrap -- wrap interactive tool sessions

See Automated Scripts & Cron for details.

What about Windows?

PowerShell is supported. shellfirm can install hooks for PowerShell and intercept commands.

Cmd.exe is not supported. shellfirm requires a shell that supports execution hooks, and cmd.exe does not provide this capability.

Windows Subsystem for Linux (WSL) is fully supported -- it runs a real Linux shell.

Is my command data sent anywhere?

No. Everything runs locally by default. shellfirm's pattern matching, context detection, and challenge prompts are all local operations.

The only exception is the optional LLM analysis feature. When enabled, the command text is sent to the configured LLM provider (e.g., Anthropic API) for semantic analysis. LLM analysis is opt-in -- it is disabled by default and requires you to set an API key and enable it explicitly.

Can I use it with tmux/screen?

Yes. Each tmux pane or screen window runs its own shell instance, and each instance has its own shellfirm hook. Context detection (git branch, k8s context, env vars) is evaluated per-pane, so different panes can have different risk levels.

How do I update shellfirm?

Homebrew

brew upgrade shellfirm

Cargo

cargo install shellfirm

This downloads the latest version and overwrites the existing binary.

GitHub Releases

Download the latest binary from the releases page and replace the existing binary.

After updating, restart your shell for the new version to take effect.

Can I disable shellfirm temporarily?

Yes. You have several options:

Set an environment variable (if your shell hook supports it):
```
SHELLFIRM_DISABLED=1 your-command
```
Use command prefix to bypass the hook:
```
\command your-command
```
Remove the hook temporarily by commenting it out in your shell config and restarting.

Does shellfirm work with sudo?

Yes. When you run sudo some-command, shellfirm checks the full command (including sudo) before it executes. If some-command matches a pattern, the challenge is triggered.

When you run sudo su to become root, shellfirm detects the root context (EUID=0) and escalates the risk level to Critical for subsequent commands.

What happens if shellfirm crashes?

If shellfirm encounters an error during the check pipeline, the command is allowed to proceed. shellfirm is designed to fail open -- a crash or error should never prevent you from using your terminal.

Can different users have different configurations?

Yes. Each user has their own settings at ~/.shellfirm/settings.yaml. Team policies (.shellfirm.yaml in the repo) apply to everyone working in that repository, but individual users can have different global settings (challenge type, severity threshold, enabled groups).

How many patterns does shellfirm include?

shellfirm ships with 100+ built-in patterns across 16 check groups covering filesystem, git, Docker, Kubernetes, AWS, Azure, GCP, Heroku, Terraform, databases (PostgreSQL, MySQL, MongoDB, Redis), and network operations. You can add custom patterns via settings or team policies.

Can I contribute new patterns?

Yes. Patterns are defined as YAML files in the shellfirm/checks/ directory of the repository. To add a new pattern:

Add a YAML entry in the appropriate group file (e.g., shellfirm/checks/git.yaml)
Add test cases in shellfirm/tests/checks/
Run cargo test --test checks to verify
Submit a pull request

See the repository for contributing guidelines.