atmos list affected

Use this command to list affected Atmos components and stacks between Git commits. View results in multiple formats including tables, JSON, YAML, CSV, or hierarchical trees with custom column selection, filtering, and sorting.

Experimental

atmos list affected --help

Usage

Execute the list affected command like this:

atmos list affected

To compare against a specific Git reference:

atmos list affected --ref refs/heads/main

tip

Run atmos list affected --help to see all the available options

Examples

List all affected components:

atmos list affected

Compare against specific branch or commit:

# Compare against main branch
atmos list affected --ref refs/heads/main

# Compare against specific commit
atmos list affected --sha abc123def456

Narrow the results by component tags or labels:

# Components tagged `production` or `tier-1`
atmos list affected --tags=production,tier-1

# Components labeled `ci: auto`
atmos list affected --labels=ci=auto

Tags match any supplied tag; labels match all supplied key=value or key:value pairs. See the shared matching rules for case sensitivity, missing metadata, and deleted components.

This command reads ATMOS_COMPONENT_TAGS and ATMOS_COMPONENT_LABELS, independently of the ATMOS_TAGS and ATMOS_LABELS variables used by describe affected and Terraform.

Output in different formats:

# JSON format
atmos list affected --format json

# YAML format
atmos list affected --format yaml

# CSV format for scripting
atmos list affected --format csv

Filter and sort results:

# Filter by specific stack
atmos list affected --stack prod-us-east-1

# Sort by component name
atmos list affected --sort component:asc

# Sort by multiple columns
atmos list affected --sort "stack:asc,component:desc"

Include dependent components:

# Show components that depend on affected components
atmos list affected --include-dependents

Filter by deletion status:

# Show only deleted components (for destroy workflows)
atmos list affected --format json | jq '[.[] | select(.deleted == true)]'

# Show only modified components (for apply workflows)
atmos list affected --format json | jq '[.[] | select(.deleted != true)]'

Custom columns:

# Simple field names
atmos list affected --columns component,stack,affected

# Named columns with templates
atmos list affected --columns "Component={{ .component }},Stack={{ .stack }}"

Working with private repositories:

# Use SSH key for cloning
atmos list affected --ssh-key ~/.ssh/id_rsa --clone-target-ref

# Use pre-cloned repository (for CI/CD)
atmos list affected --repo-path /tmp/target-repo

Flags

--ref

Git reference to compare against (e.g., refs/heads/main). Defaults to refs/remotes/origin/HEAD.
Environment variable: ATMOS_AFFECTED_REF

--sha

Git commit SHA to compare against. Takes precedence over --ref.
Environment variable: ATMOS_AFFECTED_SHA

--format / -f

Output format: table, json, yaml, csv, tsv (default: table).
Environment variable: ATMOS_LIST_FORMAT

--columns

Columns to display. Supports simple field names (e.g., component,stack), named columns with templates (e.g., "Name={{ .component }}"), or field references (e.g., "MyStack=stack").
Environment variable: ATMOS_LIST_COLUMNS

--sort

Sort by column:order (e.g., stack:asc,component:desc). Multiple sort columns separated by comma.
Environment variable: ATMOS_LIST_SORT

--delimiter

Delimiter for CSV/TSV output (default: , for CSV, \t for TSV).
Environment variable: ATMOS_LIST_DELIMITER

--stack

Filter results to a specific stack.
Environment variable: ATMOS_STACK

--include-dependents

Include dependents as separate rows with depth indicators and reason dependent. Tags and labels filter these rows while retaining matching descendants of excluded components; see dependent filtering.
Environment variable: ATMOS_AFFECTED_INCLUDE_DEPENDENTS

--exclude-locked

Exclude components with metadata.locked: true from results, including deleted components that were locked in the base ref.
Environment variable: ATMOS_AFFECTED_EXCLUDE_LOCKED

--tags

Keep only components whose metadata.tags contain any of the given comma-separated tags (e.g., --tags=production,tier-1).
Environment variable: ATMOS_COMPONENT_TAGS

--labels

Keep only components whose metadata.labels contain all of the given comma-separated key=value or key:value pairs (e.g., --labels=ci=auto). When combined with --tags, a component must satisfy both.
Environment variable: ATMOS_COMPONENT_LABELS

--repo-path

Path to already-cloned target repository. Conflicts with --ref, --sha, --ssh-key, and --ssh-key-password.
Environment variable: ATMOS_AFFECTED_REPO_PATH

--ssh-key

Path to PEM-encoded private key for SSH cloning.
Environment variable: ATMOS_AFFECTED_SSH_KEY

--ssh-key-password

Password for encrypted PEM key.
Environment variable: ATMOS_AFFECTED_SSH_KEY_PASSWORD

--clone-target-ref

Clone target reference instead of checking it out locally (default: false). Required for private repositories when SSH credentials are provided.
Environment variable: ATMOS_AFFECTED_CLONE_TARGET_REF

--process-templates

Enable/disable Go template processing (default: true).
Environment variable: ATMOS_AFFECTED_PROCESS_TEMPLATES

--process-functions

Enable/disable YAML function processing (default: true).
Environment variable: ATMOS_AFFECTED_PROCESS_FUNCTIONS

--skip

Skip specific YAML functions. Use multiple --skip flags or comma-separated values.
Environment variable: ATMOS_AFFECTED_SKIP

--identity / -i (optional)

Authenticate with a specific identity before listing affected components. Required when YAML functions need credentials.
Environment variable: ATMOS_IDENTITY

Default Columns

The default table output shows:

Column	Description
Status	Visual indicator: ● (enabled), ◐ (locked), ○ (disabled)
Component	Affected component name
Stack	Affected stack name
Type	Component type (terraform, helmfile, etc.)
Affected	Reason for being affected (component, file, folder, stack.vars, etc.)
File	External file that changed (if applicable)

Available Fields

All fields from atmos describe affected are available for custom columns:

• component - Component name
• component_type - Component type (terraform/helmfile/packer)
• component_path - Filesystem path to component
• stack - Stack name
• stack_slug - Stack-component concatenation
• namespace, tenant, environment, stage - Stack naming parts
• affected - Primary reason for being affected
• affected_all - All reasons (comma-separated)
• file - External file that changed
• folder - External folder that changed
• spacelift_stack - Spacelift stack name
• atlantis_project - Atlantis project name
• enabled - Component enabled status
• locked - Component locked status
• status - Visual status indicator
• is_dependent - Whether component is a dependent
• depth - Dependency nesting depth
• dependents_count - Number of dependent components
• deleted - Whether the component was deleted (boolean)
• deletion_type - Type of deletion: component or stack

Detecting Deleted Components

The list affected command automatically detects components and stacks that exist in the BASE branch but have been deleted in HEAD. This enables CI/CD pipelines to trigger terraform destroy for removed infrastructure.

Deleted components are identified by:

• affected: deleted - Component was removed from a stack
• affected: deleted.stack - Entire stack was deleted
• deleted: true - Boolean flag for easy filtering
• deletion_type: component or deletion_type: stack - Type of deletion

See atmos describe affected for detailed documentation on deleted detection.

Comparison with atmos describe affected

Feature	list affected	describe affected
Default format	Table	JSON
Formats supported	table, json, yaml, csv, tsv	json, yaml
Custom columns	Yes	No
Sorting	Yes (multi-column)	No
Status indicator	Yes (●/◐/○)	No
Dependencies	Flattened rows	Nested structure
Use case	Quick overview, human-readable	Full details, machine processing

Use list affected when you want a quick, scannable view of what changed. Use describe affected when you need the complete data structure for automation or detailed analysis.

Example Output

atmos list affected

┌────────┬─────────────────────┬──────────────────┬──────────┬──────────┬────────────────────────────────────────┐
│ Status │ Component           │ Stack            │ Type     │ Affected │ File                                   │
├────────┼─────────────────────┼──────────────────┼──────────┼──────────┼────────────────────────────────────────┤
│ ●      │ vpc                 │ plat-ue2-dev     │ terraform│ component│                                        │
│ ●      │ vpc                 │ plat-ue2-prod    │ terraform│ component│                                        │
│ ●      │ eks                 │ plat-ue2-dev     │ terraform│ stack.vars│                                       │
│ ◐      │ rds                 │ plat-ue2-staging │ terraform│ file     │ modules/rds/main.tf                    │
└────────┴─────────────────────┴──────────────────┴──────────┴──────────┴────────────────────────────────────────┘

Related Commands

• atmos describe affected - Get detailed affected components in JSON/YAML format
• atmos list stacks - List all stacks
• atmos list components - List all components
• atmos list instances - List all component instances