shellfirm policy

The policy command manages .shellfirm.yaml team policy files.

Usage

shellfirm policy <SUBCOMMAND>

Subcommands

validate

Validate the .shellfirm.yaml in the current directory:

shellfirm policy validate

Checks:

• YAML syntax is valid
• version field is present and correct
• Pattern IDs are properly formatted
• Regex patterns compile successfully
• Challenge types are valid
• Severity levels are valid

Exit codes:

Code	Meaning
0	Policy is valid
1	Policy has errors

Example output (valid):

Policy is valid.
  Version: 1
  Deny list: 2 patterns
  Overrides: 3 rules
  Custom checks: 1 pattern

Example output (invalid):

Error: invalid regex pattern in check 'team:bad_pattern': regex parse error

show

Display the effective policy for the current directory:

shellfirm policy show

This resolves the nearest .shellfirm.yaml and displays its contents along with merge information.

init

Create a template .shellfirm.yaml in the current directory:

shellfirm policy init

This creates a starter policy file with commented examples:

# .shellfirm.yaml
# Team safety policy for this repository.
# See https://shellfirm.dev/docs/team-policies/overview
version: 1

# Block these patterns entirely (no challenge, just denied)
deny: []
  # - "git:force_push"
  # - "fs:format_filesystem"

# Override challenge types for specific patterns
overrides: []
  # - id: "fs:recursively_delete"
  #   challenge: Yes
  # - id: "git:reset_hard"
  #   challenge: Yes
  #   on_branches: ["main", "production"]

# Add team-specific check patterns
checks: []
  # - id: "team:example"
  #   from: base
  #   test: "example_command"
  #   severity: High
  #   description: "Example custom check"

Examples

# Create a new policy template
shellfirm policy init

# Validate after editing
shellfirm policy validate

# Show the current effective policy
shellfirm policy show

CI usage

# In CI: fail if policy is invalid
shellfirm policy validate || exit 1