docs: add comprehensive Terraform planfile documentation and command reference

demo/screengrabs/demo-stacks.txt

@@ -31,21 +31,56 @@ atmos describe dependents --help
 atmos describe stacks --help
 atmos describe workflows --help
 atmos docs --help
+atmos list --help
+atmos list components --help
+atmos list metadata --help
+atmos list settings --help
+atmos list stacks --help
+atmos list values --help
+atmos list vars --help
+atmos list workflows --help
 atmos pro lock --help
 atmos pro unlock --help
 atmos terraform --help
+atmos terraform apply --help
 atmos terraform clean --help
+atmos terraform console --help
 atmos terraform deploy --help
+atmos terraform destroy --help
+atmos terraform fmt --help
+atmos terraform force-unlock --help
 atmos terraform generate --help
 atmos terraform generate backend --help
 atmos terraform generate backends --help
 atmos terraform generate planfile --help
 atmos terraform generate varfile --help
 atmos terraform generate varfiles --help
+atmos terraform get --help
+atmos terraform graph --help
+atmos terraform import --help
+atmos terraform init --help
+atmos terraform login --help
+atmos terraform logout --help
+atmos terraform metadata --help
+atmos terraform modules --help
+atmos terraform output --help
+atmos terraform plan --help
+atmos terraform plan-diff --help
+atmos terraform providers --help
+atmos terraform refresh --help
 atmos terraform shell --help
+atmos terraform show --help
+atmos terraform state --help
+atmos terraform taint --help
+atmos terraform test --help
+atmos terraform untaint --help
+atmos terraform validate --help
+atmos terraform version --help
 atmos terraform workspace --help
 atmos validate --help
 atmos validate component --help
+atmos validate editorconfig --help
+atmos validate schema --help
 atmos validate stacks --help
 atmos vendor --help
 atmos vendor pull --help

website/docs/cli/commands/terraform/terraform-apply.mdx

@@ -0,0 +1,335 @@
+---
+title: atmos terraform apply
+sidebar_label: apply
+sidebar_class_name: command
+id: apply
+---
+import Screengrab from '@site/src/components/Screengrab'
+import Terminal from '@site/src/components/Terminal'
+
+:::note purpose
+Use this command to apply Terraform changes for a component in an Atmos stack. This command can either generate a new plan and apply it, or apply a previously generated planfile.
+:::
+
+<Screengrab title="atmos terraform apply --help" slug="atmos-terraform-apply--help" />
+
+## Usage
+
+Execute the `terraform apply` command like this:
+
+```shell
+atmos terraform apply <component> -s <stack> [options]
+```
+
+This command applies Terraform changes to your infrastructure. You can:
+- Apply changes directly (generates a new plan and prompts for approval)
+- Apply a previously generated planfile using `--from-plan`
+- Apply a specific planfile using `--planfile <path>`
+- Auto-approve changes using `-auto-approve`
+
+:::tip
+For automated deployments, consider using `atmos terraform deploy` which automatically includes `-auto-approve`.
+:::
+
+## Examples
+
+### Interactive Apply
+
+Apply changes interactively (you'll be prompted to approve):
+
+```shell
+atmos terraform apply vpc -s dev
+```
+
+### Apply from Previous Plan
+
+Apply using the planfile generated by a previous `atmos terraform plan`:
+
+```shell
+# First generate a plan
+atmos terraform plan vpc -s dev
+
+# Then apply using that plan
+atmos terraform apply vpc -s dev --from-plan
+```
+
+### Apply Specific Planfile
+
+Apply a specific planfile:
+
+```shell
+# Using a custom planfile created earlier
+atmos terraform apply vpc -s dev --planfile /tmp/my-plan.tfplan
+
+# Or relative to component directory
+atmos terraform apply vpc -s dev --planfile plans/vpc.tfplan
+```
+
+### Auto-Approved Apply
+
+Apply changes without manual approval (use with caution):
+
+```shell
+atmos terraform apply vpc -s dev -auto-approve
+```
+
+### Targeted Apply
+
+Apply changes only to specific resources:
+
+```shell
+atmos terraform apply vpc -s dev -target=aws_subnet.private
+```
+
+## Planfile Usage
+
+### Using Atmos-Generated Planfiles
+
+When you run `atmos terraform plan`, Atmos automatically generates a planfile with a standardized name. You can apply this planfile using the `--from-plan` flag:
+
+```shell
+# Generate the plan
+atmos terraform plan vpc -s dev
+
+# Review the plan output...
+
+# Apply the exact plan that was generated
+atmos terraform apply vpc -s dev --from-plan
+```
+
+This ensures that only the changes you reviewed will be applied, with no risk of configuration drift between planning and applying.
+
+### Using Custom Planfiles
+
+If you generated a plan with a custom output path, use the `--planfile` flag:
+
+```shell
+# Generate plan to custom location
+atmos terraform plan vpc -s dev -out=/tmp/vpc-dev.tfplan
+
+# Apply that specific planfile
+atmos terraform apply vpc -s dev --planfile /tmp/vpc-dev.tfplan
+```
+
+### Direct Apply (No Planfile)
+
+When neither `--from-plan` nor `--planfile` is specified, Atmos will:
+1. Generate a new plan
+2. Show the planned changes
+3. Prompt for approval (unless `-auto-approve` is used)
+4. Apply the changes if approved
+
+```shell
+atmos terraform apply vpc -s dev
+```
+
+## Arguments
+
+<dl>
+    <dt>`component` <em>(required)</em></dt>
+    <dd>
+        Atmos component name to apply.
+    </dd>
+</dl>
+
+## Flags
+
+<dl>
+    <dt>`--stack` / `-s` <em>(required)</em></dt>
+    <dd>
+        Atmos stack name where the component is defined.
+    </dd>
+
+    <dt>`--from-plan` <em>(optional)</em></dt>
+    <dd>
+        Apply the planfile previously generated by `atmos terraform plan`.
+
+        The planfile must exist in the component directory with the standard Atmos naming convention.
+
+        ```shell
+        atmos terraform apply vpc -s dev --from-plan
+        ```
+    </dd>
+
+    <dt>`--planfile` <em>(optional)</em></dt>
+    <dd>
+        Apply a specific planfile at the given path.
+
+        Use this instead of the native Terraform planfile argument.
+
+        ```shell
+        atmos terraform apply vpc -s dev --planfile /path/to/plan.tfplan
+        ```
+    </dd>
+
+    <dt>`--affected` <em>(optional)</em></dt>
+    <dd>
+        Apply only affected components based on changes in the repository.
+
+        ```shell
+        atmos terraform apply --affected
+        ```
+    </dd>
+
+    <dt>`--all` <em>(optional)</em></dt>
+    <dd>
+        Apply all components in all stacks (use with extreme caution).
+
+        ```shell
+        atmos terraform apply --all
+        ```
+    </dd>
+
+    <dt>`--dry-run` <em>(optional)</em></dt>
+    <dd>
+        Show what would be executed without actually running the apply.
+
+        ```shell
+        atmos terraform apply vpc -s dev --dry-run
+        ```
+    </dd>
+
+    <dt>`--skip-init` <em>(optional)</em></dt>
+    <dd>
+        Skip running `terraform init` before applying.
+
+        ```shell
+        atmos terraform apply vpc -s dev --skip-init
+        ```
+    </dd>
+
+    <dt>`--process-templates` <em>(optional)</em></dt>
+    <dd>
+        Enable/disable Go template processing in Atmos stack manifests.
+
+        Default: `true`
+
+        ```shell
+        atmos terraform apply vpc -s dev --process-templates=false
+        ```
+    </dd>
+</dl>
+
+## Native Terraform Flags
+
+The `atmos terraform apply` command supports all native `terraform apply` flags. Some commonly used flags include:
+
+<dl>
+    <dt>`-auto-approve`</dt>
+    <dd>
+        Apply changes without manual approval prompt.
+
+        ```shell
+        atmos terraform apply vpc -s dev -auto-approve
+        ```
+
+        :::warning
+        Use `-auto-approve` with caution, especially in production environments.
+        :::
+    </dd>
+
+    <dt>`-target=RESOURCE`</dt>
+    <dd>
+        Apply changes only to specific resources. Can be specified multiple times.
+
+        ```shell
+        atmos terraform apply vpc -s dev -target=aws_subnet.private -target=aws_route_table.private
+        ```
+    </dd>
+
+    <dt>`-var 'NAME=VALUE'`</dt>
+    <dd>
+        Set a variable value. Can be specified multiple times.
+
+        ```shell
+        atmos terraform apply vpc -s dev -var="instance_count=3"
+        ```
+    </dd>
+
+    <dt>`-refresh-only`</dt>
+    <dd>
+        Only update the state to match remote systems.
+
+        ```shell
+        atmos terraform apply vpc -s dev -refresh-only
+        ```
+    </dd>
+
+    <dt>`-replace=RESOURCE`</dt>
+    <dd>
+        Force replacement of a specific resource.
+
+        ```shell
+        atmos terraform apply vpc -s dev -replace=aws_instance.web
+        ```
+    </dd>
+</dl>
+
+## Best Practices
+
+### Two-Stage Apply Process
+
+For production environments, we recommend a two-stage apply process:
+
+```shell
+# Stage 1: Generate and review the plan
+atmos terraform plan vpc -s prod
+
+# Review the plan output carefully...
+
+# Stage 2: Apply the exact reviewed plan
+atmos terraform apply vpc -s prod --from-plan
+```
+
+This ensures that:
+- Changes are reviewed before applying
+- No configuration drift occurs between plan and apply
+- The exact reviewed changes are applied
+
+### Automated Deployments
+
+For CI/CD pipelines, you can:
+
+1. Generate a plan in one job:
+   ```shell
+   atmos terraform plan vpc -s prod -out=plan.tfplan
+   ```
+
+2. Apply the plan in another job (after approval):
+   ```shell
+   atmos terraform apply vpc -s prod --planfile plan.tfplan
+   ```
+
+Or use `atmos terraform deploy` for fully automated deployments:
+```shell
+atmos terraform deploy vpc -s prod
+```
+
+## Related Commands
+
+- [`atmos terraform plan`](/cli/commands/terraform/plan) - Generate an execution plan
+- [`atmos terraform deploy`](/cli/commands/terraform/deploy) - Apply with auto-approval
+- [`atmos terraform destroy`](/cli/commands/terraform/destroy) - Destroy infrastructure
+- [`atmos terraform plan-diff`](/cli/commands/terraform/plan-diff) - Compare plan files
+
+## Configuration
+
+Configure default behavior for `terraform apply` in your `atmos.yaml`:
+
+```yaml
+components:
+  terraform:
+    # Auto-approve all applies (use with caution)
+    apply_auto_approve: false
+
+    # Auto-generate backend configuration
+    auto_generate_backend_file: true
+```
+
+:::info
+See [Terraform Planfiles](/core-concepts/terraform/planfiles) for a comprehensive guide on working with planfiles in Atmos.
+:::
+
+:::note
+The `atmos terraform apply` command supports all native `terraform apply` options described in [Terraform apply options](https://developer.hashicorp.com/terraform/cli/commands/apply#apply-options), except that planfile arguments should use `--from-plan` or `--planfile` flags instead of being passed directly.
+:::