# atmos terraform migrate plan

Use `atmos terraform migrate plan` to preview a user-authored `tfmigrate` migration for an Atmos Terraform component.

> ⚠️ Experimental

## Usage

```shell
atmos terraform migrate plan [component] -s <stack> [options]
```

## Arguments

- **`component`** — Atmos Terraform component to migrate. Omit when selecting multiple components with `--all`, `--components`, `--query`, or `--affected`.

## Flags

- **`--stack` / `-s`** — Atmos stack where the component is defined.
- **`--identity` / `-i`** — Identity to authenticate before resolving the component and running `tfmigrate plan`. Environment variable: `ATMOS_IDENTITY`.
- **`--migration`** — Path to a single `tfmigrate` migration file, relative to `migration_dir`. Do not include the `migration_dir` prefix. `migration_dir` defaults to `./migrations` when that directory exists in the component, otherwise it defaults to the component root. Omit this flag to let `tfmigrate` run history mode.
- **`--tfmigrate-config`** — Override the `tfmigrate` config path. Atmos checks, in order: this flag or `ATMOS_TFMIGRATE_CONFIG`, then `TFMIGRATE_CONFIG`, then a `.tfmigrate.hcl` file in the component. When none of these are set, Atmos generates a config that reuses the component's Terraform backend as history storage.
- **`--backend-config`** — Backend config entry passed to `tfmigrate --backend-config`. Repeat the flag for multiple entries.
- **`--all`** — Run the migration plan for all selected component instances.
- **`--components`** — Run the migration plan for the listed component names.
- **`--query`** — Run the migration plan for component instances matching a YQ expression.
- **`--affected`** — Run the migration plan for affected Terraform components. `--include-dependents` is not supported for migrate yet.
- **`--skip-init`** — Skip the normal Terraform init path before `tfmigrate` runs.

## Examples

Preview history-mode migrations:

```shell
atmos terraform migrate plan s3-bucket -s plat-ue2-dev
```

Preview with an explicit identity:

```shell
atmos terraform migrate plan s3-bucket -s plat-ue2-dev --identity aws-prod
```

Preview a single-file migration:

```shell
atmos terraform migrate plan s3-bucket -s plat-ue2-dev --migration 001_remove_template_provider.hcl
```

`tfmigrate` resolves the value relative to the `migration_dir` in its config. Pass just the filename when `migration_dir` already points at your migrations directory.

Preview migrations across selected components:

```shell
atmos terraform migrate plan --all --components s3-bucket
atmos terraform migrate plan --query '.settings.requires_migration == true'
```

Override the default `tfmigrate` config path:

```shell
atmos terraform migrate plan s3-bucket -s plat-ue2-dev --tfmigrate-config migrations/.tfmigrate.hcl
```

## Related

- [`atmos terraform migrate`](/cli/commands/terraform/migrate)
- [`atmos terraform migrate apply`](/cli/commands/terraform/migrate-apply)
- [`atmos terraform migrate list`](/cli/commands/terraform/migrate-list)