# atmos aws cloudformation diff

Create a CloudFormation changeset for the component, render the predicted
changes, and delete the changeset again without executing it. `diff` authenticates and calls the
CloudFormation API — it previews what `apply` would actually do to the live
stack, unlike [`render`](/cli/commands/aws/cloudformation/render), which never
leaves the local template.

> ⚠️ Experimental

## Usage

```shell
atmos aws cloudformation diff <component> --stack <stack> [options]
```

```shell
atmos aws cloudformation diff vpc -s plat-ue2-dev
```

Diff all or affected components in dependency order:

```shell
atmos aws cloudformation diff --all -s plat-ue2-dev
atmos aws cloudformation diff --affected --base origin/main
```

Diff components filtered by tags or labels (composes with `--all`/`--affected` to narrow the selected set further):

```shell
atmos aws cloudformation diff --all --tags production,tier-1
atmos aws cloudformation diff --affected --labels cost-center=platform
```

## Behavior

`diff` leaves nothing behind. It deletes the preview changeset after rendering it,
including when the changeset would change nothing (CloudFormation reports that as
a `FAILED` changeset, "didn't contain changes").

For a component that has never been deployed, CloudFormation registers an empty
`REVIEW_IN_PROGRESS` stack as soon as the changeset is created. When `diff`
created that stack itself, it deletes it again after removing the changeset,
having first confirmed it is still `REVIEW_IN_PROGRESS`, so a preview never
leaves a stub that `list` would show as managed. A stack that already existed,
including an empty `REVIEW_IN_PROGRESS` stub left by an earlier run, is never
deleted.

A stack in `ROLLBACK_COMPLETE` cannot be updated, so `diff` fails with an
explanation and a hint to run
[`atmos aws cloudformation delete`](/cli/commands/aws/cloudformation/delete) for
the component and apply again.

## Flags

- **`--stack`, `-s` (required for a single component)**
  Atmos stack. Required when operating on a single component; optional (and used only to narrow the selected set) with 
  `--all`
  /
  `--affected`
  .

:::note
[`atmos aws cloudformation plan`](/cli/commands/aws/cloudformation/plan) is an alias for `diff`.
Both fire the `before.aws/cloudformation.diff`/`after.aws/cloudformation.diff` hook events.
:::