Skip to main content

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

--blast-radius-max-time​

Sets the maximum time duration for blast radius calculation. When the time limit is reached, the analysis gracefully continues with risks identified up to that point, rather than failing.

# Quick timeout for fast feedback
overmind changes submit-plan tfplan.json --blast-radius-max-time 5m

# Extended timeout for complex changes
overmind changes submit-plan tfplan.json --blast-radius-max-time 20m

# Default behavior (10 minutes)
overmind changes submit-plan tfplan.json

When to adjust:

  • Shorter timeouts (1-5m): For rapid feedback cycles or routine changes where partial analysis is acceptable
  • Standard timeout (10m): Default that works well for most infrastructure changes
  • Longer timeouts (15-30m): For complex dependency graphs requiring comprehensive analysis
  • Valid range: 1 minute to 30 minutes

Note: You can specify --blast-radius-max-time independently without setting --blast-radius-link-depth or --blast-radius-max-items. When you do this, your account's default settings will be used for link depth and max items, while only the time limit is customized.

Behavior when timeout is reached:

The system gracefully continues with the partial blast radius results collected up to that point. This means:

  • All risks identified before the timeout will be analyzed
  • The analysis completes successfully (not treated as a failure)
  • Logs and metrics track when timeouts occur for monitoring purposes
  • You can increase the timeout for future runs if more comprehensive analysis is needed

Combining parameters:

# Balanced configuration for most changes
overmind changes submit-plan tfplan.json \
  --blast-radius-link-depth 3 \
  --blast-radius-max-items 500 \
  --blast-radius-max-time 10m

# Fast configuration for quick feedback
overmind changes submit-plan tfplan.json \
  --blast-radius-link-depth 2 \
  --blast-radius-max-items 200 \
  --blast-radius-max-time 5m

# Comprehensive configuration for critical changes
overmind changes submit-plan tfplan.json \
  --blast-radius-link-depth 5 \
  --blast-radius-max-items 1000 \
  --blast-radius-max-time 20m

Labels​

You can add colored labels to visually categorize changes. Labels are available for overmind terraform plan and overmind changes submit-plan commands.

--labels​

Apply colored labels to visually categorize changes. Labels include both a name and a color, making them ideal for visual organization and quick identification in the Overmind interface.

Usage:

# Single label
overmind changes submit-plan tfplan.json --labels "critical=FF0000"

# Multiple labels (comma-separated)
overmind changes submit-plan tfplan.json --labels "critical=FF0000,review=FFFF00"

# Multiple labels (repeated flag)
overmind changes submit-plan tfplan.json --labels "critical=FF0000" --labels "review=FFFF00"

# With terraform command
overmind terraform plan --labels "production=00FF00"

Format: Labels must be specified in name=color format where:

  • name: The label name (cannot be empty)
  • color: A 6-digit hexadecimal color code (with or without leading #)

Color format:

  • Use 6 hex digits: FF0000 (red), 00FF00 (green), 0000FF (blue)
  • Leading # is optional: #FF0000 or FF0000 both work
  • Colors are normalized to uppercase: ff0000 becomes #FF0000

Examples:

# Production change with red critical label
overmind changes submit-plan tfplan.json \
  --labels "critical=FF0000"

# Staging change with multiple labels
overmind terraform plan \
  --labels "staging=FFFF00" \
  --labels "needs-review=FFA500"

Combining with other flags:

# Complete example with labels and blast radius settings
overmind changes submit-plan tfplan.json \
  --labels "critical=FF0000" \
  --blast-radius-link-depth 5 \
  --blast-radius-max-items 1000

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 \
  --blast-radius-max-time 5m

For critical changes:

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

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 \
      --labels "critical=FF0000" \
      --blast-radius-link-depth 3 \
      --blast-radius-max-items 500 \
      --blast-radius-max-time 10m

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
  • Decrease --blast-radius-max-time for quicker results with partial analysis

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.