CLI Configuration

The Overmind CLI supports several configuration options to customize change analysis. Configuration can be specified via command-line flags or configuration files in your project.

Blast Radius Parameters

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

info

Blast radius parameters (--blast-radius-link-depth, --blast-radius-max-items, --change-analysis-target-duration) are only available with overmind changes submit-plan. When using overmind terraform plan, blast radius settings are controlled by your account defaults in the Overmind UI.

--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

--change-analysis-target-duration

Sets the target duration for change analysis planning. This is NOT a hard deadline - the blast radius phase uses 67% of this target to determine when to stop gracefully, and the remaining 33% is available for hypothesis formation and risk investigation.

Important: The analysis can run slightly past this target time. The job is only hard-stopped at the service maximum of 30 minutes to ensure you don't lose all work if the analysis takes a bit longer than expected.

# Quick target for fast feedback
overmind changes submit-plan tfplan.json --change-analysis-target-duration 5m

# Extended target for complex changes
overmind changes submit-plan tfplan.json --change-analysis-target-duration 20m

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

When to adjust:

• Shorter targets (3-5m): For rapid feedback cycles on routine changes where you're willing to accept less complete blast radius coverage
• Standard target (10m): Default that works well for most infrastructure changes
• Longer targets (15-30m): For complex dependency graphs requiring comprehensive analysis
• Valid range: 1 minute to 30 minutes

Note: You can specify --change-analysis-target-duration 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 target duration is customized.

How it works:

• Blast radius phase: Gets 67% of the target duration. When this soft timeout is reached, blast radius stops gracefully and returns partial results.
• Form hypotheses & investigate: Uses the remaining 33% of the target duration plus any buffer up to the hard max (30 minutes).
• Hard maximum: The job is only forcibly stopped at 30 minutes. If you set a 10-minute target and the job needs 11 minutes, you still get your results.

Combining parameters:

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

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

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

--blast-radius-max-time (Deprecated)

Deprecated

This flag is deprecated and will be removed in a future release. Use --change-analysis-target-duration instead.

Tags

You can add tags to categorize and filter changes. Tags are available for both overmind terraform plan and overmind changes submit-plan commands.

--tags

Apply key-value tags to your changes for organization and filtering.

Usage:

# Single tag
overmind terraform plan --tags "env=production"

# Multiple tags (comma-separated)
overmind terraform plan --tags "env=production,team=platform"

# Multiple tags (repeated flag)
overmind terraform plan --tags "env=production" --tags "team=platform"

Format: Tags must be specified in key=value format.

Examples:

# Tag a production change
overmind terraform plan --tags "env=production"

# Tag with multiple values
overmind terraform plan \
  --tags "env=staging" \
  --tags "team=infrastructure"

# Use with submit-plan
overmind changes submit-plan tfplan.json --tags "env=production"

Configuration Files

Overmind supports local configuration files to maintain consistency across team deployments and automate common tasks. These files live in the .overmind/ directory within your Terraform project.

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.

info

Signal configuration is only available with overmind changes submit-plan. When using overmind terraform plan, signal configuration is handled server-side using settings configured in the Overmind UI.

Usage:

# Signal config is automatically applied from default location
overmind changes submit-plan tfplan.json

# Override with a 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 (e.g., --signal-config custom-config.yaml)
2. Project directory: .overmind/ folder in current working directory
3. UI fallback: Configuration from the Overmind web interface

Example Project Structure

Here is an example project structure:

your-terraform-project/
├── .overmind/
│   ├── 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/signal-config.yaml

Performance Tuning

Blast radius tuning is available when using overmind changes submit-plan:

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

When using overmind terraform plan, blast radius settings are controlled by your account defaults configured in the Overmind UI.

CI/CD Integration

Option 1: Use overmind terraform plan (recommended)

The simplest approach—Overmind handles plan creation and analysis automatically:

# GitHub Actions example
- name: Analyze Terraform Changes
  run: |
    overmind terraform plan \
      --ticket-link "${{ github.event.pull_request.html_url }}" \
      --tags "env=production"

Option 2: Use overmind changes submit-plan

For pipelines where you need fine-grained control over blast radius settings or already have an existing plan file:

# GitHub Actions example
- name: Create Terraform Plan
  run: terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json

- name: Submit Plan to Overmind
  run: |
    overmind changes submit-plan tfplan.json \
      --tags "env=production" \
      --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 terraform plan 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 terraform plan --help for parameter details

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