docs: refactor terraform usage page

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

@@ -323,6 +323,96 @@ Or use `atmos terraform deploy` for fully automated deployments:
 atmos terraform deploy vpc -s prod
 ```
 
+## Multi-Component Operations
+
+Execute `terraform apply` across multiple components using filtering flags. All flags can be combined with `--dry-run` to preview what would be executed.
+
+:::warning
+Multi-component apply operations can make significant infrastructure changes. Always use `--dry-run` first to verify which components will be affected.
+:::
+
+### Apply All Components
+
+```shell
+# Apply all components in all stacks
+atmos terraform apply --all
+
+# Apply all components in a specific stack
+atmos terraform apply --all --stack prod
+atmos terraform apply --stack prod
+```
+
+### Apply Affected Components
+
+Apply only components affected by changes in the current branch (requires git). Components are processed in dependency order:
+
+```shell
+# Apply affected components in all stacks
+atmos terraform apply --affected
+
+# Apply affected components in a specific stack
+atmos terraform apply --affected --stack prod
+
+# Include dependent components (components that depend on affected components)
+atmos terraform apply --affected --include-dependents
+
+# Clone the target reference instead of checking it out
+atmos terraform apply --affected --clone-target-ref=true
+```
+
+### Apply Specific Components
+
+```shell
+# Apply specific components in all stacks
+atmos terraform apply --components vpc,eks
+
+# Apply specific components in a specific stack
+atmos terraform apply --components vpc,eks --stack prod
+```
+
+### Apply Components by Query
+
+Filter components using [YQ](https://mikefarah.gitbook.io/yq) expressions against component configuration:
+
+```shell
+# Apply components where team tag equals "eks"
+atmos terraform apply --query '.vars.tags.team == "eks"'
+
+# Apply components in a specific account
+atmos terraform apply --query '.settings.context.account_id == 12345'
+
+# Combine with stack filter
+atmos terraform apply --query '.vars.tags.team == "eks"' --stack prod
+```
+
+### Multi-Component Flags
+
+<dl>
+    <dt>`--all`</dt>
+    <dd>Apply all components in all stacks (or specified stack with `--stack`).</dd>
+
+    <dt>`--affected`</dt>
+    <dd>Apply components affected by git changes in dependency order. Supports all flags from [`atmos describe affected`](/cli/commands/describe/affected).</dd>
+
+    <dt>`--components`</dt>
+    <dd>Apply specific components by name (comma-separated or repeated flag).</dd>
+
+    <dt>`--query`</dt>
+    <dd>Apply components matching a YQ expression. All Atmos sections are available: `vars`, `settings`, `env`, `metadata`, etc.</dd>
+
+    <dt>`--include-dependents`</dt>
+    <dd>With `--affected`, also apply components that depend on affected components, recursively.</dd>
+
+    <dt>`--ref`</dt>
+    <dd>Git reference to compare against (branch or tag). Default: `refs/remotes/origin/HEAD`.</dd>
+
+    <dt>`--sha`</dt>
+    <dd>Git commit SHA to compare against.</dd>
+
+    <dt>`--clone-target-ref`</dt>
+    <dd>Clone the target reference instead of checking it out locally.</dd>
+</dl>
+
 ## Related Commands
 
 - [`atmos terraform plan`](/cli/commands/terraform/plan) - Generate an execution plan

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

@@ -194,6 +194,96 @@ can't be provided on the command line. To use a previously generated planfile, u
 
 See [Terraform Planfiles](/components/terraform/planfiles) for a comprehensive guide on working with planfiles in Atmos.
 
+## Multi-Component Operations
+
+Execute `terraform deploy` across multiple components using filtering flags. Since deploy auto-approves, this is particularly powerful for automated deployments. All flags can be combined with `--dry-run` to preview what would be executed.
+
+:::warning
+Multi-component deploy operations will auto-approve all changes. Use `--dry-run` first to verify which components will be affected.
+:::
+
+### Deploy All Components
+
+```shell
+# Deploy all components in all stacks
+atmos terraform deploy --all
+
+# Deploy all components in a specific stack
+atmos terraform deploy --all --stack prod
+atmos terraform deploy --stack prod
+```
+
+### Deploy Affected Components
+
+Deploy only components affected by changes in the current branch (requires git). Components are processed in dependency order:
+
+```shell
+# Deploy affected components in all stacks
+atmos terraform deploy --affected
+
+# Deploy affected components in a specific stack
+atmos terraform deploy --affected --stack prod
+
+# Include dependent components (components that depend on affected components)
+atmos terraform deploy --affected --include-dependents
+
+# Clone the target reference instead of checking it out
+atmos terraform deploy --affected --clone-target-ref=true
+```
+
+### Deploy Specific Components
+
+```shell
+# Deploy specific components in all stacks
+atmos terraform deploy --components vpc,eks
+
+# Deploy specific components in a specific stack
+atmos terraform deploy --components vpc,eks --stack prod
+```
+
+### Deploy Components by Query
+
+Filter components using [YQ](https://mikefarah.gitbook.io/yq) expressions against component configuration:
+
+```shell
+# Deploy components where team tag equals "eks"
+atmos terraform deploy --query '.vars.tags.team == "eks"'
+
+# Deploy components in a specific account
+atmos terraform deploy --query '.settings.context.account_id == 12345'
+
+# Combine with stack filter
+atmos terraform deploy --query '.vars.tags.team == "eks"' --stack prod
+```
+
+### Multi-Component Flags
+
+<dl>
+    <dt>`--all`</dt>
+    <dd>Deploy all components in all stacks (or specified stack with `--stack`).</dd>
+
+    <dt>`--affected`</dt>
+    <dd>Deploy components affected by git changes in dependency order. Supports all flags from [`atmos describe affected`](/cli/commands/describe/affected).</dd>
+
+    <dt>`--components`</dt>
+    <dd>Deploy specific components by name (comma-separated or repeated flag).</dd>
+
+    <dt>`--query`</dt>
+    <dd>Deploy components matching a YQ expression. All Atmos sections are available: `vars`, `settings`, `env`, `metadata`, etc.</dd>
+
+    <dt>`--include-dependents`</dt>
+    <dd>With `--affected`, also deploy components that depend on affected components, recursively.</dd>
+
+    <dt>`--ref`</dt>
+    <dd>Git reference to compare against (branch or tag). Default: `refs/remotes/origin/HEAD`.</dd>
+
+    <dt>`--sha`</dt>
+    <dd>Git commit SHA to compare against.</dd>
+
+    <dt>`--clone-target-ref`</dt>
+    <dd>Clone the target reference instead of checking it out locally.</dd>
+</dl>
+
 ## Related Commands
 
 - [terraform plan](/cli/commands/terraform/plan) - Generate an execution plan

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

@@ -277,6 +277,92 @@ Some commonly used native flags include:
     </dd>
 </dl>
 
+## Multi-Component Operations
+
+Execute `terraform plan` across multiple components using filtering flags. All flags can be combined with `--dry-run` to preview what would be executed.
+
+### Plan All Components
+
+```shell
+# Plan all components in all stacks
+atmos terraform plan --all
+
+# Plan all components in a specific stack
+atmos terraform plan --all --stack prod
+atmos terraform plan --stack prod
+```
+
+### Plan Affected Components
+
+Plan only components affected by changes in the current branch (requires git):
+
+```shell
+# Plan affected components in all stacks
+atmos terraform plan --affected
+
+# Plan affected components in a specific stack
+atmos terraform plan --affected --stack prod
+
+# Include dependent components (components that depend on affected components)
+atmos terraform plan --affected --include-dependents
+
+# Clone the target reference instead of checking it out
+atmos terraform plan --affected --clone-target-ref=true
+```
+
+### Plan Specific Components
+
+```shell
+# Plan specific components in all stacks
+atmos terraform plan --components vpc,eks
+
+# Plan specific components in a specific stack
+atmos terraform plan --components vpc,eks --stack prod
+```
+
+### Plan Components by Query
+
+Filter components using [YQ](https://mikefarah.gitbook.io/yq) expressions against component configuration:
+
+```shell
+# Plan components where team tag equals "eks"
+atmos terraform plan --query '.vars.tags.team == "eks"'
+
+# Plan components in a specific account
+atmos terraform plan --query '.settings.context.account_id == 12345'
+
+# Combine with stack filter
+atmos terraform plan --query '.vars.tags.team == "eks"' --stack prod
+```
+
+### Multi-Component Flags
+
+<dl>
+    <dt>`--all`</dt>
+    <dd>Plan all components in all stacks (or specified stack with `--stack`).</dd>
+
+    <dt>`--affected`</dt>
+    <dd>Plan components affected by git changes in dependency order. Supports all flags from [`atmos describe affected`](/cli/commands/describe/affected).</dd>
+
+    <dt>`--components`</dt>
+    <dd>Plan specific components by name (comma-separated or repeated flag).</dd>
+
+    <dt>`--query`</dt>
+    <dd>Plan components matching a YQ expression. All Atmos sections are available: `vars`, `settings`, `env`, `metadata`, etc.</dd>
+
+    <dt>`--include-dependents`</dt>
+    <dd>With `--affected`, also plan components that depend on affected components, recursively.</dd>
+
+    <dt>`--ref`</dt>
+    <dd>Git reference to compare against (branch or tag). Default: `refs/remotes/origin/HEAD`.</dd>
+
+    <dt>`--sha`</dt>
+    <dd>Git commit SHA to compare against.</dd>
+
+    <dt>`--clone-target-ref`</dt>
+    <dd>Clone the target reference instead of checking it out locally.</dd>
+</dl>
+
 ## Related Commands
 
 - [`atmos terraform apply`](/cli/commands/terraform/apply) - Apply the changes from a plan