Settings Reference

shellfirm's user configuration lives at ~/.shellfirm/settings.yaml (or the platform-specific config directory). This page documents every configurable field.

Configuration location

The settings file is located at your platform's config directory:

• macOS: ~/Library/Application Support/shellfirm/settings.yaml
• Linux: ~/.config/shellfirm/settings.yaml

If the file does not exist, shellfirm uses default values for all settings.

Viewing current configuration

shellfirm status

To view a human-readable summary:

shellfirm config show

Modifying settings

Via themed CLI subcommands

shellfirm config challenge Yes                           # Set challenge type
shellfirm config severity Medium                         # Set minimum severity
shellfirm config groups --enable aws --disable heroku    # Manage check groups
shellfirm config ignore git:interactive_rebase           # Ignore a pattern
shellfirm config deny kubernetes:delete_namespace        # Deny a pattern
shellfirm config llm --provider anthropic                # Configure LLM
shellfirm config context                                 # Configure context settings

Via interactive menu

shellfirm config

Opens an interactive menu to configure any setting.

Via file

Edit the settings file directly:

shellfirm config edit

Full reference

Top-level settings

Key	Type	Default	Description
challenge	string	Math	Default challenge type: Math, Enter, or Yes
enabled_groups	string[]	(all 16 groups)	Check groups to enable
disabled_groups	string[]	[]	Check groups to disable (applied after enabled_groups)
ignores_patterns_ids	string[]	[]	Pattern IDs to skip entirely
deny_patterns_ids	string[]	[]	Pattern IDs to deny (block without challenge)
min_severity	string or null	null	Minimum severity to trigger a challenge (Info, Low, Medium, High, Critical, or null for all)
audit_enabled	boolean	true	Enable audit trail logging
blast_radius	boolean	true	Enable blast radius computation

Context settings (context.*)

Key	Type	Default	Description
context.protected_branches	string[]	["main", "master", "production", "release/*"]	Git branches that trigger Critical risk
context.production_k8s_patterns	string[]	["prod", "production", "prd", "live"]	Substrings in k8s context names that trigger Critical risk
context.production_env_vars	map	{NODE_ENV: production, RAILS_ENV: production, ENVIRONMENT: production}	Env var name-value pairs that trigger Critical risk
context.sensitive_paths	string[]	[]	File paths to flag as sensitive

Escalation settings (context.escalation.*)

Key	Type	Default	Description
context.escalation.elevated	string	Enter	Minimum challenge type for Elevated risk level
context.escalation.critical	string	Yes	Minimum challenge type for Critical risk level

Severity escalation settings (severity_escalation.*)

Severity escalation sets a challenge floor based on the matched check's severity level. This is ON by default — Critical severity checks require Yes and High severity checks require Enter, even without any context signals.

Key	Type	Default	Description
severity_escalation.enabled	boolean	true	Enable severity-based challenge escalation
severity_escalation.critical	string	Yes	Minimum challenge for Critical severity checks
severity_escalation.high	string	Enter	Minimum challenge for High severity checks
severity_escalation.medium	string	Math	Minimum challenge for Medium severity checks
severity_escalation.low	string	Math	Minimum challenge for Low severity checks
severity_escalation.info	string	Math	Minimum challenge for Info severity checks

Per-group and per-check escalation

Key	Type	Default	Description
group_escalation	map	{}	Per-group minimum challenge overrides. Keys are group names (e.g., fs, git), values are challenge types.
check_escalation	map	{}	Per-check-id minimum challenge overrides. Keys are check IDs (e.g., git:force_push), values are challenge types.

Agent settings (agent.*)

Key	Type	Default	Description
agent.auto_deny_severity	string	High	Auto-deny commands at or above this severity in agent mode
agent.require_human_approval	boolean	false	Flag denied commands for human review

LLM settings (llm.*)

LLM analysis is not configured by default. To enable it, add an llm section to your settings file or use shellfirm config llm.

Key	Type	Default	Description
llm	object or null	null	LLM configuration block. When absent, LLM analysis is disabled.
llm.provider	string	anthropic	LLM provider: anthropic or openai-compatible
llm.model	string	claude-sonnet-4-20250514	Model ID for analysis
llm.base_url	string or null	null	Custom API base URL (for openai-compatible providers)
llm.timeout_ms	integer	5000	API request timeout in milliseconds
llm.max_tokens	integer	512	Maximum tokens in LLM response

Wrapper settings (wrappers.*)

Key	Type	Default	Description
wrappers.tools.<name>.delimiter	string	;	Statement delimiter for the named tool
wrappers.tools.<name>.check_groups	string[]	[] (uses global)	Check groups active for this tool

Example configuration

Minimal configuration (sparse file)

shellfirm uses defaults for any missing field, so you only need to specify what you want to change. Severity escalation is ON by default (Critical→Yes, High→Enter), so even a minimal config gets severity-based protection:

challenge: Enter
min_severity: Medium

Full configuration

challenge: Math
enabled_groups:
  - aws
  - azure
  - base
  - database
  - docker
  - fs
  - gcp
  - git
  - heroku
  - kubernetes
  - mongodb
  - mysql
  - network
  - psql
  - redis
  - terraform
disabled_groups: []
ignores_patterns_ids: []
deny_patterns_ids: []
min_severity: null
audit_enabled: true
blast_radius: true

# Severity escalation (all fields optional, shown with defaults)
severity_escalation:
  enabled: true
  critical: "Yes"
  high: Enter
  medium: Math
  low: Math
  info: Math
group_escalation: {}
check_escalation: {}

context:
  protected_branches:
    - main
    - master
    - production
    - "release/*"
  production_k8s_patterns:
    - prod
    - production
    - prd
    - live
  production_env_vars:
    NODE_ENV: production
    RAILS_ENV: production
    ENVIRONMENT: production
  sensitive_paths: []
  escalation:
    elevated: Enter
    critical: Yes

agent:
  auto_deny_severity: High
  require_human_approval: false

# llm: (not configured by default)
#   provider: anthropic
#   model: claude-sonnet-4-20250514
#   timeout_ms: 5000
#   max_tokens: 512

wrappers:
  tools:
    psql:
      delimiter: ";"
      check_groups:
        - psql
        - database
    mysql:
      delimiter: ";"
      check_groups:
        - mysql
        - database
    redis-cli:
      delimiter: "\n"
      check_groups:
        - redis

Environment variables

Variable	Description
SHELLFIRM_LLM_API_KEY	API key for the configured LLM provider
SHELLFIRM_LLM_PROVIDER	Override the LLM provider setting
SHELLFIRM_CONFIG_PATH	Override the configuration directory path

Resetting configuration

To reset to defaults:

shellfirm config reset

This offers two options:

1. Replace the current settings file with defaults
2. Backup the current file and create a new default one