# 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[Read more](/stacks/dependencies/components)

## Usage

```shell
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`](/cli/commands/terraform/plan) |
| Helmfile | `atmos helmfile diff` |
| Helm | [`atmos helm plan`](/cli/commands/helm/plan) |
| Kubernetes | [`atmos kubernetes plan`](/cli/commands/kubernetes/plan) |
| AWS CloudFormation | [`atmos aws cloudformation plan`](/cli/commands/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

```shell
# 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](/cli/commands/stack/stack-deploy#ci)
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.