CLI Commands

The overmind changes command group manages the full lifecycle of an infrastructure change: submitting plans, running impact analysis, fetching results, and tracking deployments. These commands are used in CI/CD pipelines, custom integrations, and interactive workflows.

In CI/CD, set the OVM_API_KEY environment variable to authenticate (see Creating an API Key). For interactive use, the CLI supports OAuth authentication through the browser -- just run the command and follow the prompts.

submit-plan

Creates a new Change from one or more Terraform/OpenTofu plan files and optionally starts blast radius analysis.

overmind changes submit-plan [FLAGS] FILE [FILE ...]

Each FILE must be a JSON plan file generated by terraform show -json tfplan > FILE.

Key flags

Flag	Default	Description
--ticket-link	*	Link to the PR or ticket. Used as a unique identifier for the change -- multiple runs with the same ticket link update the same change.
--no-start	false	Store planned changes without starting analysis. Use with start-analysis to trigger analysis after all plans are submitted.
--comment	false	Request the GitHub App to post analysis results as a PR comment. Requires the Overmind GitHub App installed with pull_requests:write permission.
--title	auto-detected	Short title for the change. If omitted, Overmind generates one from git describe and the current user.
--description		Description of the change.
--tags		Key=value tags for categorization (e.g. env=production,team=platform).

Analysis configuration flags (--blast-radius-link-depth, --blast-radius-max-items, --change-analysis-target-duration, --signal-config) are also available. See the CLI Configuration guide for details.

Single-plan workflow

The default behavior submits the plan and immediately starts analysis:

terraform plan -out=tfplan
terraform show -json tfplan > tfplan.json

overmind changes submit-plan \
  --ticket-link "https://github.com/org/repo/pull/42" \
  tfplan.json

The command prints the change URL to stdout. To have the GitHub App post results directly on the PR:

overmind changes submit-plan \
  --comment \
  --ticket-link "https://github.com/org/repo/pull/42" \
  tfplan.json

Multi-plan workflow

For parallel planning systems (Atlantis, CI matrix builds), submit each plan with --no-start and then trigger analysis separately with start-analysis:

# Job 1: submit networking plan
overmind changes submit-plan --no-start \
  --ticket-link "$PR_URL" \
  tfplan-networking.json

# Job 2: submit compute plan
overmind changes submit-plan --no-start \
  --ticket-link "$PR_URL" \
  tfplan-compute.json

# Final step: trigger analysis on the accumulated plans
overmind changes start-analysis \
  --comment \
  --ticket-link "$PR_URL"

All plans submitted with the same --ticket-link are accumulated on a single Change. The start-analysis call triggers blast radius analysis across all of them.

---

start-analysis

Triggers blast radius analysis on a Change that already has planned changes stored via submit-plan --no-start. The Change must be in DEFINING status with at least one stored plan.

overmind changes start-analysis {--ticket-link URL | --uuid ID | --change URL}

Key flags

Flag	Default	Description
--ticket-link		Identify the change by its ticket link (must match a DEFINING change).
--uuid		Identify the change by UUID.
--change		Identify the change by its Overmind URL.
--comment	false	Request the GitHub App to post results as a PR comment.
--wait	false	Block until analysis completes before returning.

These three identification flags are mutually exclusive -- use exactly one.

Analysis configuration flags (--blast-radius-link-depth, --blast-radius-max-items, etc.) are also available and override account-level defaults for this analysis run.

Example

overmind changes start-analysis \
  --comment \
  --ticket-link "https://github.com/org/repo/pull/42"

---

get-change

Retrieves the summary of an existing Change, including blast radius and risks.

overmind changes get-change {--uuid ID | --change URL}

Key flags

Flag	Default	Description
--change		Identify the change by its Overmind URL.
--uuid		Identify the change by UUID.
--ticket-link		Identify the change by its ticket link.
--wait	true	Wait for analysis to complete before returning. Set --wait=false to return immediately with whatever status is available.
--format	json	Output format: json or markdown.
--status	CHANGE_STATUS_DEFINING	Expected change status when using --ticket-link.
--risk-levels	high,medium,low	Filter results by risk severity.

Examples

Wait for analysis and get a markdown summary:

overmind changes get-change \
  --change "https://app.overmind.tech/changes/UUID" \
  --format markdown

Return immediately without waiting:

overmind changes get-change \
  --change "https://app.overmind.tech/changes/UUID" \
  --wait=false \
  --format json

---

start-change

Marks a Change as "starting" just before a deployment begins. This captures a snapshot of the current system state for later comparison.

overmind changes start-change --uuid ID

Example

CHANGE_ID=$(cat .overmind-change-id)
overmind changes start-change --uuid "$CHANGE_ID"

terraform apply tfplan

overmind changes end-change --uuid "$CHANGE_ID"

---

end-change

Marks a Change as "complete" after a deployment finishes. This captures a post-deployment snapshot and closes the change lifecycle.

overmind changes end-change --uuid ID

Typically called immediately after terraform apply (or equivalent) completes, whether the apply succeeded or failed. See the start-change example above for the full pattern.

---

Multi-Plan Workflow (end-to-end)

This diagram shows the full lifecycle for a parallel planning setup (e.g. Atlantis with multiple projects):

sequenceDiagram
    participant CI1 as CI Job 1
    participant CI2 as CI Job 2
    participant Final as Final Step
    participant OVM as Overmind
    participant GH as GitHub App

    CI1->>OVM: submit-plan --no-start (networking)
    CI2->>OVM: submit-plan --no-start (compute)
    Note over OVM: Plans accumulated on same Change
    Final->>OVM: start-analysis --comment
    OVM-->>Final: Change URL + GITHUB_APP_ACTIVE
    Note over OVM: Blast radius analysis runs async
    OVM->>GH: Analysis complete
    GH->>GH: Post PR comment with results

1. Plan phase: Each CI job runs terraform plan and submits its plan with submit-plan --no-start --ticket-link "$PR_URL". All plans accumulate on a single Change identified by the ticket link.
2. Analysis phase: A final step calls start-analysis --comment --ticket-link "$PR_URL" to trigger blast radius analysis across all accumulated plans.
3. Results: When the GitHub App is installed, it posts results directly on the PR. Otherwise, use get-change --format markdown to retrieve results for posting.
4. Deploy phase: Wrap the deployment with start-change / end-change to capture before/after system snapshots.