Configuration

shellfirm stores its configuration in ~/.config/shellfirm/settings.yaml. The configuration file is optional -- shellfirm uses sensible defaults when no file exists.

Configuration file location

The default location is platform-dependent:

Platform	Path
macOS	`~/Library/Application Support/shellfirm/settings.yaml`
Linux	`~/.config/shellfirm/settings.yaml`

To find your exact path:

shellfirm status

Managing configuration

shellfirm config

Running config with no subcommand opens an interactive menu showing all configurable sections with their current values. Select any item to configure it.

View current settings

shellfirm config show

Displays a human-readable summary of your current configuration, grouped by section.

Themed subcommands

Each configuration area has its own subcommand for quick, scriptable changes:

shellfirm config challenge Yes          # Set challenge type
shellfirm config severity High          # 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 --model claude-sonnet-4-20250514  # Configure LLM
shellfirm config context                # Interactive context sub-menu

Run any themed subcommand without arguments for an interactive prompt:

shellfirm config challenge              # Interactive select
shellfirm config severity               # Interactive select
shellfirm config groups                 # Interactive multi-select
shellfirm config llm                    # Interactive prompts for each field

Edit in your editor

shellfirm config edit

Opens the settings file in your $EDITOR.

Reset to defaults

shellfirm config reset

You will be prompted to either overwrite or back up your current settings.

Complete settings reference

challenge

The default challenge type for all interceptions.

Value	Description
`Math`	Solve a simple arithmetic problem (default)
`Enter`	Press Enter to confirm
`Yes`	Type "yes" to confirm

challenge: Math

min_severity

Minimum severity for a check to trigger a challenge. Checks below this threshold are skipped (but still logged as Skipped in the audit trail).

Value	What triggers
`null`	Everything (default)
`Info`	Info and above
`Low`	Low and above
`Medium`	Medium and above
`High`	High and above
`Critical`	Critical only

min_severity: null

enabled_groups

List of check groups that are active. All 16 groups are enabled by default.

enabled_groups:
  - aws
  - azure
  - base
  - database
  - docker
  - fs
  - gcp
  - git
  - heroku
  - kubernetes
  - mongodb
  - mysql
  - network
  - psql
  - redis
  - terraform

disabled_groups

List of check groups to disable. Applied after enabled_groups.

disabled_groups:
  - fs-strict
  - git-strict
  - kubernetes-strict

ignores_patterns_ids

List of specific pattern IDs to ignore (never trigger).

ignores_patterns_ids:
  - git:interactive_rebase
  - git:cherry_pick

deny_patterns_ids

List of pattern IDs that are unconditionally denied (cannot be solved with a challenge).

deny_patterns_ids:
  - kubernetes:delete_namespace
  - terraform:apply_with_auto_approve

audit_enabled

Enable or disable the audit trail.

audit_enabled: true   # default

blast_radius

Enable or disable runtime blast radius computation.

blast_radius: true   # default

context

Context-aware protection settings.

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

See Context-Aware Protection for details.

agent

AI agent guardrail configuration.

agent:
  auto_deny_severity: High   # default
  require_human_approval: false

See Agents & Automation for details.

llm

LLM-powered analysis configuration (requires the llm feature). Not configured by default -- you must explicitly enable it:

llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  base_url: null
  timeout_ms: 5000
  max_tokens: 512

When llm is not set, LLM analysis is disabled.

wrappers

PTY wrapper configuration for shellfirm wrap.

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

See Interactive Wrapper for details.

Sparse configuration

shellfirm uses a sparse configuration model. You only need to specify values that differ from the defaults. Unspecified values are filled in with defaults at runtime.

For example, a minimal configuration that just changes the challenge type:

challenge: Yes

All other settings (enabled_groups, context, audit, blast_radius, etc.) use their defaults.