atmos stack plan

Review proposed infrastructure changes before deployment by running each selected component's native plan or diff operation in dependency order.

Configure component dependencies

Declare the prerequisites that determine planning and deployment order.

Component dependencies

atmos stack plan --help

Usage

atmos stack plan --stack=prod
atmos stack plan --stack=prod --component=network,app
atmos stack plan --all
atmos stack plan --affected --base=origin/main

With --stack=prod, Atmos selects every component in that stack that supports planning. Use --component=network,app, repeated --component flags, or both to narrow the selection. Names match across component kinds; each matching kind and stack runs once. Positional component arguments are not accepted. Unknown names are errors.

Without --stack, --all, or --affected, Atmos prompts for a stack that has at least one enabled, unlocked, non-abstract component supporting the requested operation. Bare --component opens a multiselect picker, with any explicitly supplied names already selected. Cancellation or an empty component selection stops before execution. Both prompts work during --dry-run. In CI, without an interactive terminal, or with --interactive=false, supply explicit values instead.

Supported component kinds

Component kind	Native command
Terraform	atmos terraform plan
Helmfile	atmos helmfile diff
Helm	atmos helm plan
Kubernetes	atmos kubernetes plan
AWS CloudFormation	atmos aws cloudformation plan
Custom kinds	A custom command named plan declaring component.type and component/stack bindings

Kinds without a registered plan handler, such as Packer, are excluded with a notice. If no eligible components remain, Atmos reports that no components matched. It does not substitute a build or deployment. Custom kinds support stack selection, --component, --all, and dependency expansion; affected detection does not yet select custom kinds.

The native commands retain their authentication, hooks, state inspection, and plan or diff output. Helm, Helmfile, Kubernetes, and CloudFormation use their native diff hook events; Terraform uses its native plan hook events. Use the component-specific commands when you need their engine-specific flags.

Plan and dry run

Running stack plan executes the native planning operations. These may contact providers or clusters, initialize working directories, produce plan files, or create CloudFormation change sets. They do not apply the proposed changes. Configured hooks and custom commands retain their own behavior.

Running stack plan --dry-run only displays the selected commands, dependencies, and hook declarations. It does not execute native plans, diffs, or hooks and does not calculate infrastructure changes. A stack plan does not create a shared approval artifact for a later stack deploy.

Planning a prerequisite does not deploy it or make its proposed outputs available to dependents. Native operations use the currently available state and outputs.

Examples

# Plan several components with repeated and comma-separated selectors.
atmos stack plan --stack=prod --component=network,app --component=database

# Choose components interactively and preview the commands without executing them.
atmos stack plan --stack=prod --component --dry-run

# Plan changed components and their prerequisites.
atmos stack plan --affected --base=origin/main --include-dependencies

# Plan independent components concurrently, continuing independent branches on failure.
atmos stack plan --stack=prod --max-concurrency=2 --failure-mode=keep-going

Execution and results

Plans run in dependency order. Unselected prerequisites do not run unless included with --include-dependencies; expansion can cross stacks and component names. Unselected prerequisites do not need a plan handler. Explicit dependency expansion fails before execution if a required prerequisite within the requested depth has no plan handler; optional unsupported prerequisites are omitted.

With fail-fast, a failed operation stops pending operations. With keep-going, independent branches continue while dependents of the failed operation are skipped. Failures return a nonzero exit status. The final tally reports succeeded, failed, skipped, and excluded components.

Each component runs in an isolated Atmos process. Terraform components sharing a source directory are serialized, and concurrent workers disable the shared plugin cache. One worker preserves interactive input; concurrent workers require a noninteractive identity. Native plan handlers do not require --auto-approve.

CI mode collects child summaries and outputs into the combined stack report using the same CI output fields and configuration as other stack lifecycle operations. Dry runs do not publish execution results. Deleted affected definitions are reported and omitted because they are unavailable in the current configuration; this command does not plan their teardown.

Before execution, Atmos checks named identities and component authentication defaults across the selected components. An undefined identity stops the operation before any component starts and includes matching profile suggestions when available. This check does not log in; credential acquisition remains with each component command. Dry runs and --identity=false bypass this authentication check.

Skipped status lines include the reason, such as fail-fast after terraform/dev/vpc failed, dependency terraform/dev/vpc failed, or context canceled.

Flags

--component[=names]

Filter by exact component names across kinds. Repeat the flag or comma-separate names; matching any supplied name is sufficient. With no value, open a multiselect picker. Supplied names start selected when combined with a bare flag. Empty names and empty picker selections are errors. Omit the flag to select every eligible component in the chosen scope. Dependency expansion can add other names.

--all

Select every component that defines a plan operation. May be narrowed by component names, stack, tags, or labels. Cannot combine --all and --affected. Default: false.

--affected

Select components affected by the Git comparison. May be narrowed by component names, stack, tags, or labels. Cannot combine --all and --affected. Default: false.

--tags

Select components whose metadata.tags include any of the given tags (comma-separated). Selects matching components in a supplied or prompted stack. With component names, --all, or --affected, it narrows that selection. Dependency expansion still follows declared dependencies regardless of tags. Environment variable: ATMOS_TAGS. Default: No tag filter.

--labels

Select components whose metadata.labels contain every given key=value (or key:value) pair. Repeat the flag or separate pairs with commas. Used alone or combined like --tags; when both are given, a component must match both. Environment variable: ATMOS_LABELS. Default: No label filter.

--stack, -s

Intersect the initial selection with a canonical stack name. A name that matches no stack is an error. Environment variable: ATMOS_STACK. Without --all or --affected, a missing stack is prompted interactively or reported as an error. With either bulk flag, omitting this selects across stacks.

--base

Base Git ref or SHA for the comparison. Atmos detects it automatically in supported CI environments. Requires --affected. Default: Existing affected baseline rules.

--ref

Git reference to compare against. Requires --affected.

--sha

Git SHA to compare against. Requires --affected.

--repo-path

Existing repository to use as the comparison baseline. Requires --affected; cannot be combined with --base, --ref, --sha, --ssh-key, --ssh-key-password, or --clone-target-ref.

--ssh-key

SSH key for cloning the comparison baseline. Requires --affected.

--ssh-key-password

Password for the SSH key. Requires --affected.

--clone-target-ref

Clone the comparison baseline. Requires --affected. Default: false.

--include-dependencies[=N]

Include prerequisites of the selected components. The bare flag expands without a depth limit; use the =N form, such as --include-dependencies=2, to limit the depth. Default: Disabled.

--include-dependents[=N]

Include consumers of the selected components. The bare flag expands without a depth limit; use the =N form to limit the depth. Default: Disabled.

--max-concurrency

Maximum number of active component operations. One worker permits interactive prompts. Default: 1.

--failure-mode

fail-fast stops at the first failure. keep-going finishes independent branches while dependents of failures are skipped. Default: fail-fast.

--log-order

stream prints component output as it arrives. grouped emits complete component logs in stable dependency order and applies when --max-concurrency is greater than 1. Grouped mode shows live start and completion messages on stderr while buffering child logs. It sends each component's stdout to stdout and its headers and stderr to stderr. Default: stream.

--dry-run

Preview selection, commands, relationships, and lifecycle hooks without running plans, diffs, or hooks. Environment variable: ATMOS_DRY_RUN. Default: false.

--identity, -i

Forward the identity to each child. Use --identity without a value to select interactively, which requires --max-concurrency=1. Environment variable: ATMOS_IDENTITY. Default: Component command behavior.

--auto-approve

Append each handler's registered approval arguments. Built-in plan handlers do not register approval arguments, so this flag adds nothing to their commands. Default: false.

--ci

Run in CI mode. Every child component command runs with ATMOS_CI=true, and Atmos publishes one combined job summary and one set of outputs for the whole run. Without the flag, CI mode turns on when ATMOS_CI or CI is truthy or a CI provider is detected; an explicit --ci=false turns it off. Environment variables: ATMOS_CI, CI. Default: false.

--skip-hooks[=names]

Skip all hooks, or the comma-separated hook names; previews identify skipped hooks. Environment variable: ATMOS_SKIP_HOOKS.

Comparison flags (--base, --ref, --sha, --repo-path, --ssh-key, --ssh-key-password, and --clone-target-ref) require --affected and are rejected otherwise. Only the environment variables listed above apply to this command. Variables that other commands bind to similar settings, such as ATMOS_TERRAFORM_DESTROY_ALL, do not change the selection.