CLI Configuration

The Overmind CLI supports several configuration files that help customize your workflow and analysis settings. These files live in the .overmind/ directory within your Terraform project and provide persistent configuration for your team.

Blast Radius Parameters

Control the depth and scope of dependency analysis with these CLI parameters:

--blast-radius-link-depth

Sets how many levels deep Overmind should follow resource relationships when calculating blast radius.

# Shallow analysis - faster, might miss some dependencies
overmind changes submit-plan tfplan.json --blast-radius-link-depth 1

# Deep analysis - thorough, takes longer
overmind changes submit-plan tfplan.json --blast-radius-link-depth 5

# Default behavior (uses account settings)
overmind changes submit-plan tfplan.json

When to adjust:

• Lower values (1-2): For quick checks or simple changes
• Higher values (4-6): For critical changes where you need complete dependency mapping with no time constraints
• Default (account settings): Works well for most infrastructure changes

--blast-radius-max-items

Limits the total number of resources included in blast radius calculation to prevent analysis from becoming overwhelming.

# Limit to 100 resources for focused analysis
overmind changes submit-plan tfplan.json --blast-radius-max-items 100

# Allow larger blast radius for complex changes
overmind changes submit-plan tfplan.json --blast-radius-max-items 1000

# Default behavior (uses account settings)
overmind changes submit-plan tfplan.json

Practical usage:

• Lower limits: Faster analysis, good for routine changes
• Higher limits: Complete analysis for complex infrastructure
• Very high limits: Use cautiously as analysis time increases significantly

Configuration Files

Overmind supports local configuration files to maintain consistency across team deployments and automate common tasks.

Auto-Tag Rules File

Create .overmind/auto-tag-rules.yaml to define automatic tagging rules for your changes.

Usage:

# Apply auto-tag rules from file
overmind changes submit-plan tfplan.json

# Override with different rules file
overmind changes submit-plan tfplan.json --auto-tag-rules custom-rules.yaml

File format:

rules:
  - name: My test rule in prod
    tag_key: prod
    enabled: true
    instructions: always set it to prod
    valid_values:
      - dogfood
      - prod

Rule structure:

• name: Human-readable description of the rule
• tag_key: The tag that appears on changes
• enabled: Whether to apply this rule
• instructions: Criteria for when to apply the tag
• valid_values: Optional list of allowed values for the tag

Signals Configuration

Default location: .overmind/signal-config.yaml CLI parameter: --signal-config

Defines signals that help Overmind identify changes with typically lower risk. Changes receive reduced risk scores and can be handled with less scrutiny. These override the default signals that are configured in the Overmind web interface.

There are 2 types of signals that can be configured on a per repository basis:

• Routine Changes: Defines patterns that help Overmind identify changes with typically lower risk. Changes receive reduced risk scores and can be handled with less scrutiny.
• GitHub App Signals: Defines signals that help Overmind identify changes with typically lower risk. Changes receive reduced risk scores and can be handled with less scrutiny. This is only available if the Overmind GitHub App is installed and configured.

Usage:

# Use signal config from file if it exists
overmind changes submit-plan tfplan.json

# Override with different config
overmind changes submit-plan tfplan.json --signal-config team-config.yaml

File format:

routine_changes_config:
  sensitivity: 0.7          # >= 0
  duration_in_days: 14      # >= 1
  events_per_day: 5         # >= 1
github_organisation_profile:
  primary_branch_name: main

Configuration options:

Routine Changes Configuration:

• sensitivity: How responsive to frequency variations (must be positive)
• duration_in_days: How many days of history to consider (minimum 1)
• events_per_day: Expected frequency of changes per day (minimum 1)

GitHub App Signals Configuration:

• primary_branch_name: The name of the primary branch for the repository

This configuration helps Overmind determine what constitutes "low risk" vs "high risk" changes for your infrastructure.

Configuration File Discovery

The CLI looks for configuration files in this order:

1. Explicit flags: Files specified with CLI parameters
2. Project directory: .overmind/ folder in current directory
3. Parent directories: Searches upward through directory tree
4. UI fallback: Configuration from the Overmind web interface

Example Project Structure

Here is an example projcet structure:

your-terraform-project/
├── .overmind/
│   ├── auto-tag-rules.yaml
│   ├── signal-config.yaml
│   └── plan.out
├── main.tf
├── variables.tf
└── terraform.tfstate

Configuration Best Practices

Team Configuration

Version control your config files:

# Include in your repository
git add .overmind/auto-tag-rules.yaml
git add .overmind/signal-config.yaml

Performance Tuning

For routine changes:

# Quick analysis for frequent deployments
overmind changes submit-plan tfplan.json --blast-radius-link-depth 2 --blast-radius-max-items 200

For critical changes:

# Deep analysis for important infrastructure
overmind changes submit-plan tfplan.json --blast-radius-link-depth 5 --blast-radius-max-items 1000

CI/CD Integration

# GitHub Actions example
- name: Submit Terraform Plan
  run: |
    overmind changes submit-plan tfplan.json \
      --auto-tag-rules .overmind/auto-tag-rules.yaml \
      --signal-config .overmind/signal-config.yaml \
      --blast-radius-link-depth 3 \
      --blast-radius-max-items 500

GitHub App Configuration Checklist

Once the Overmind GitHub App is installed, verify the following before relying on GitHub-driven signals:

1. Install the app on the right repos: Connect the repositories that correspond to your Terraform environments or deployment orchestrations.
2. Generate signal-config.yaml: Use the app setup flow or copy the template above, then commit it to .overmind/ alongside your other configuration files.
3. Validate CLI usage: Run overmind changes submit-plan with the --signal-config flag (or rely on automatic discovery) to include branch context and deployment cadence in risk analysis.
4. Review signals output: After submitting a plan, open the change in Overmind to confirm GitHub App Signals appear. Refer to the GitHub App Signals documentation if adjustments are needed.

Troubleshooting Configuration

Configuration not loading:

• Verify file paths and YAML syntax
• Check that files are readable by the CLI
• Ensure you're running from the correct directory

Performance issues:

• Reduce --blast-radius-max-items for faster analysis
• Lower --blast-radius-link-depth for simpler changes

Getting file formats:

• Use the Overmind web interface to configure rules and export the format
• Run overmind changes submit-plan --help for parameter details

For additional help, visit our support documentation or join our Discord community.