# 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)