fix: Adding missing cautionary asides (#3970)

* fix: Adding cautions for `run` command

* fix: Adding missing cautionary asides

* fix: Addressing CodeRabbit feedback

* Update docs-starlight/src/content/docs/02-features/02-stacks.mdx

Co-authored-by: Brian T <[email protected]>

* Update docs-starlight/src/content/docs/02-features/02-stacks.mdx

Co-authored-by: Brian T <[email protected]>

* Update docs-starlight/src/content/docs/02-features/02-stacks.mdx

Co-authored-by: Brian T <[email protected]>

* Update docs-starlight/src/data/flags/dependency-fetch-output-from-state.mdx

Co-authored-by: Brian T <[email protected]>

---------

Co-authored-by: Brian T <[email protected]>

docs-starlight/src/content/docs/02-features/02-stacks.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 2
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { Aside, FileTree } from '@astrojs/starlight/components';
 
 ## Motivation
 
@@ -107,9 +107,15 @@ terragrunt run --all plan
 
 \* Note that the units _might_ run concurrently, but some units can be blocked from running until their dependencies are run.
 
-If your units have dependencies between them, for example, you can’t deploy the backend-app until MySQL and redis are deployed. You’ll need to express those dependencies in your Terragrunt configuration as explained in the next section.
+If your units have dependencies between them, for example, you can’t deploy the backend-app until MySQL and valkey are deployed. You’ll need to express those dependencies in your Terragrunt configuration as explained in the next section.
 
-Additional note: If your units have dependencies between them, and you run a `terragrunt run --all destroy` command, Terragrunt will destroy all the units under the current working directory, _as well as each of the unit dependencies_ (that is, units you depend on via `dependencies` and `dependency` blocks)! If you wish to prevent external dependencies from being destroyed, add the `--queue-exclude-external` flag, or use the `--exclude-dir` once for each directory you wish to exclude.
+<Aside type="danger">
+If your units have dependencies between them, and you run a `terragrunt run --all destroy` command, Terragrunt will destroy all the units under the current working directory, _as well as each of the unit dependencies_ (that is, units you depend on via `dependencies` and `dependency` blocks)!
+
+In the above example- this would mean that destroying the backend-app would also destroy Valkey and MySQL!
+
+If you wish to prevent external dependencies from being destroyed, add the [`--queue-exclude-external` flag](/docs/reference/cli/commands/run#queue-exclude-external), or use the [`--exclude-dir` flag](/docs/reference/cli/commands/run#exclude-dir) once for each directory you wish to exclude.
+</Aside>
 
 ## Cutting down the file count
 
@@ -356,7 +362,13 @@ Any error encountered in an individual unit during a `run --all` command will pr
 
 To check all of your dependencies and validate the code in them, you can use the `run --all validate` command.
 
-**Note:** During `destroy` runs, Terragrunt will try to find all dependent units and show a confirmation prompt with a list of detected dependencies. This is because Terragrunt knows that once resources in a dependency are destroyed, any commands run on dependent units may fail. For example, if `destroy` was called on the `redis` unit, you'll be asked for confirmation, as the `backend-app` depends on `redis`. You can avoid the prompt by using `--non-interactive`.
+<Aside type="note">
+During `destroy` runs, Terragrunt will try to find all dependent units and show a confirmation prompt with a list of detected dependencies.
+
+This is because Terragrunt knows that once resources in a dependency are destroyed, any commands run on dependent units may fail.
+
+For example, if `destroy` was called on the `Valkey` unit, you'd be asked for confirmation, as the `backend-app` depends on `Valkey`. You can suppress the prompt by using the `--non-interactive` flag.
+</Aside>
 
 ## Visualizing the DAG
 

docs-starlight/src/content/docs/04-reference/02-cli/02-commands/hcl/0902-lint.md

@@ -0,0 +1,13 @@
+---
+title: lint
+description: Lint Terragrunt HCL configuration.
+slug: docs/reference/cli/commands/hcl/lint
+sidebar:
+  order: 902
+  badge:
+    text: exp
+    variant: tip
+---
+
+<!-- This page is intentionally empty. Commands are defined in `src/pages/docs/reference/cli/commands/[...slug.astro] -->
+<!-- This file is a placeholder to ensure that other pages see commands in their sidebars, and so that the data is accessible in the docs collection. -->

docs-starlight/src/data/commands/hcl/lint.mdx

@@ -0,0 +1,27 @@
+---
+name: lint
+path: hcl/lint
+category: configuration
+sidebar:
+  order: 902
+description: Lint Terragrunt HCL configuration.
+usage: |
+   Lint Terragrunt HCL configuration.
+experiment:
+  control: cli-redesign
+  name: cli redesign
+examples:
+  - description: Lint all HCL files in the current directory.
+    code: |
+      terragrunt hcl lint
+  - description: Throw an error if any variables are not set by the module a unit provisions.
+    code: |
+      terragrunt hcl lint --inputs
+  - description: Throw an error if any inputs are set that are not defined in the module.
+    code: |
+      terragrunt hcl lint --inputs --strict
+
+flags:
+  - hcl-lint-inputs
+  - hcl-lint-strict
+---

docs-starlight/src/data/commands/run.mdx

@@ -74,6 +74,8 @@ flags:
   - use-partial-parse-config-cache
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 ## Running multiple units
 
 Note that the `run` command is a more explicit and flexible way to run OpenTofu/Terraform commands in comparison to [OpenTofu shortcuts](/docs/reference/cli/commands/opentofu-shortcuts).
@@ -90,3 +92,19 @@ You may, at times, need to explicitly separate the arguments used for Terragrunt
 ```bash
 terragrunt run -- plan -no-color
 ```
+
+<Aside type="caution">
+When using `run --all plan` with units that have dependencies (e.g. via `dependency` or `dependencies` blocks), the command will fail if those dependencies have never been deployed. This is because Terragrunt cannot resolve dependency outputs without existing state.
+
+To work around this issue, use [mock outputs in dependency blocks](/docs/reference/hcl/blocks/#dependency).
+</Aside>
+
+<Aside type="caution">
+Do not set `TF_PLUGIN_CACHE_DIR` when using `run --all`. This can cause concurrent access issues with the provider cache. Instead, use Terragrunt's built-in [Provider Cache Server](/docs/features/provider-cache-server/).
+
+We are working with the OpenTofu team to improve this behavior in the future.
+</Aside>
+
+<Aside type="caution">
+When using `run --all` with `apply` or `destroy`, Terragrunt automatically adds the `-auto-approve` flag due to limitations with shared stdin making individual approvals impossible.
+</Aside>

docs-starlight/src/data/flags/all.mdx

@@ -6,6 +6,8 @@ env:
   - TG_ALL
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against all units in the current stack. This is useful when you want to apply changes across multiple units at once.
 
 For example:
@@ -17,3 +19,17 @@ terragrunt run --all plan
 This will run the `plan` command against all units in the current stack.
 
 To learn more about how to use this flag, see the [Stacks](/docs/features/stacks/#the-run---all-command) feature documentation.
+
+<Aside type="note">
+Terragrunt has a notion of "external dependencies". These are units that are not part of the current stack, from the perspective of the current working directory, but are dependencies of units that are part of the current stack.
+
+When running an `--all` command, Terragrunt will discover any external dependencies and prompt you to confirm that you want to run them as well.
+
+If you would like to suppress this prompt, you can use the [`--non-interactive` flag](/docs/reference/cli/commands/run#non-interactive). You can also prevent this behavior by setting  [`--queue-exclude-external`](/docs/reference/cli/commands/run#queue-exclude-external).
+</Aside>
+
+<Aside type="danger">
+When running a `run --all destroy` command, Terragrunt will destroy all dependencies of the units under the current working directory, in addition to the units themselves by default!
+
+If you wish to prevent external dependencies from being destroyed, add the [`--queue-exclude-external` flag](/docs/reference/cli/commands/run#queue-exclude-external), or use the [`--exclude-dir` flag](/docs/reference/cli/commands/run#exclude-dir) once for each directory you wish to exclude.
+</Aside>

docs-starlight/src/data/flags/auth-provider-cmd.mdx

@@ -7,6 +7,8 @@ env:
   - TG_AUTH_PROVIDER_CMD
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 The command and arguments used to obtain authentication credentials dynamically. If specified, Terragrunt runs this command whenever it might need authentication. This includes HCL parsing, where it might be useful to authenticate with a cloud provider _before_ running HCL functions like [`get_aws_account_id`](/docs/reference/hcl/functions#get_aws_account_id) where authentication has to already have taken place. It can also be useful for HCL functions like [`run_cmd`](/docs/reference/hcl/functions#run_cmd) where it may be useful to be authenticated before calling the function.
 
 The output must be valid JSON of the following schema:
@@ -52,5 +54,10 @@ Similarly, if you would like Terragrunt to assume an AWS role on your behalf, yo
 
 Other credential configurations will be supported in the future, but until then, if your provider authenticates via environment variables, you can use the `envs` field to fetch credentials dynamically from a secret store, etc before Terragrunt executes any IAC.
 
-**Note**: The `awsRole` configuration is only used when the `awsCredentials` configuration is not present. If both are present, the `awsCredentials` configuration will take precedence.
+<Aside type="note">
+The `awsRole` configuration is only used when the `awsCredentials` configuration is not present. If both are present, the `awsCredentials` configuration will take precedence.
+</Aside>
 
+<Aside type="caution">
+When using `iam-assume-role`, AWS authentication takes place right before a Terraform run, after `terragrunt.hcl` files are fully parsed. This means HCL functions like `get_aws_account_id` and `run_cmd` will not run with the assumed role credentials. If you need roles to be assumed prior to parsing configurations, use `auth-provider-cmd` instead.
+</Aside>

docs-starlight/src/data/flags/dependency-fetch-output-from-state.mdx

@@ -6,8 +6,16 @@ env:
   - TG_DEPENDENCY_FETCH_OUTPUT_FROM_STATE
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 This flag modifies how Terragrunt retrieves output values from dependent units. When enabled, Terragrunt will read the outputs directly from the state file instead of running `terraform output` or `tofu output`.
 
 The main benefit this flag provides is performance. Reading directly from state is typically faster than executing the OpenTofu/Terraform binary to get the same outputs.
 
 The limitation of this approach is that it is only supported by the S3 backend, and OpenTofu/Terraform may change the schema of the state file in the future, breaking this functionality.
+
+<Aside type="caution">
+This is an experimental feature. When enabled, Terragrunt will fetch dependency outputs directly from the state file instead of using `tofu output`.
+
+Currently, only the S3 backend is supported. Use with caution in production environments, as this feature is experimental and may change in the future.
+</Aside>

docs-starlight/src/data/flags/download-dir.mdx

@@ -6,8 +6,14 @@ env:
   - TG_DOWNLOAD_DIR
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 Specifies a custom directory where Terragrunt will download and cache OpenTofu/Terraform modules.
 
 By default, modules are downloaded to `.terragrunt-cache` in the working directory.
 
-This flag is not recommended as a mechanism for sharing providers between units. Instead, use the [Provider Cache Server](/docs/features/provider-cache-server) feature.
+<Aside type="note">
+The download directory (`.terragrunt-cache` by default) can grow significantly over time with multiple versions of modules.
+
+Remember to add this directory to your `.gitignore` file and consider periodic cleanup of old cached content.
+</Aside>

docs-starlight/src/data/flags/graph.mdx

@@ -6,6 +6,8 @@ env:
   - TG_GRAPH
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory. The graph consists of all units that depend on the unit in the current working directory via a `dependency` or `dependencies` blocks, plus all the units that depend on those units, and all the units that depend on those units, and so on, recursively up the tree, up to the Git repository root.
 
 The command will be executed following the order of dependencies: it'll run on the unit in the current working directory first, then on units that depend on it directly, then on the units that depend on those units, and so on. Note that if the command is `destroy`, it will run in the opposite order (the final dependents, then their dependencies, etc. up to the unit you ran the command in).
@@ -71,3 +73,15 @@ Notes:
 - `lambda` units aren't affected at all
 
 To learn more about how to use this flag, see the [Stacks](/docs/features/stacks) feature documentation.
+
+<Aside type="caution">
+When running `graph destroy`, the execution order is reversed compared to other commands. Dependencies will be destroyed in reverse order to ensure resources are safely removed (dependents are destroyed before their dependencies).
+
+Always verify the execution plan before running destructive commands.
+</Aside>
+
+<Aside type="danger">
+External dependencies (units outside your current working directory) are not automatically included in graph runs.
+
+You must explicitly include them using [`--queue-include-external`](/docs/reference/cli/commands/run#queue-include-external) if they need to be part of the execution.
+</Aside>

docs-starlight/src/data/flags/hcl-lint-inputs.mdx

@@ -0,0 +1,15 @@
+---
+name: inputs
+description: Validate that all variables are set by the module a unit provisions.
+type: bool
+env:
+  - TG_HCLVALIDATE_INPUTS
+---
+
+When enabled, Terragrunt will validate that all variables are set by the module a unit provisions.
+
+Example:
+
+```bash
+terragrunt hcl lint --inputs
+```

docs-starlight/src/data/flags/hcl-lint-strict.mdx

@@ -0,0 +1,15 @@
+---
+name: strict
+description: Throw an error if any inputs are set that are not defined in the module that a unit provisions.
+type: bool
+env:
+  - TG_HCLVALIDATE_STRICT
+---
+
+When enabled, Terragrunt will throw an error if any inputs are set that are not defined in the module that a unit provisions.
+
+Example:
+
+```bash
+terragrunt hcl lint --inputs --strict
+```

docs-starlight/src/data/flags/no-auto-init.mdx

@@ -6,6 +6,14 @@ env:
   - TG_NO_AUTO_INIT
 ---
 
-When enabled, Terragrunt will not automatically run `init` before other OpenTofu/Terraform commands. This means you'll need to manually run `init` when required.
+import { Aside } from '@astrojs/starlight/components';
+
+When enabled, Terragrunt will not automatically run `init` before other OpenTofu/Terraform commands.
 
 To learn more about how to use this flag, see the [Auto-init](/docs/features/auto-init) feature documentation.
+
+<Aside type="caution">
+When `--no-auto-init` is enabled, you must manually run `terragrunt init` if needed. Terragrunt will fail if it detects that initialization is required but auto-init is disabled.
+
+This is particularly important when using custom plugin directories or when working in CI/CD environments.
+</Aside>

docs-starlight/src/data/flags/no-destroy-dependencies-check.mdx

@@ -6,6 +6,12 @@ env:
   - TG_NO_DESTROY_DEPENDENCIES_CHECK
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 Disables Terragrunt's dependency validation during destroy operations. When enabled, Terragrunt will not verify if there are dependent units that would be affected by destroying the current unit.
 
 This results in faster destroy operations, but may result in orphaned resources.
+
+<Aside type="caution">
+Disabling dependency checks during destroy operations can lead to orphaned resources or broken infrastructure dependencies.
+</Aside>

docs-starlight/src/data/flags/non-interactive.mdx

@@ -6,4 +6,12 @@ env:
   - TG_NON_INTERACTIVE
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 When enabled, Terragrunt will automatically answer "yes" to any prompts that would normally require user input. This is particularly useful in automated environments or CI/CD pipelines where user interaction isn't possible.
+
+<Aside type="caution">
+When using `--non-interactive`, Terragrunt will automatically answer "yes" to all prompts except for external dependency inclusion prompts.
+
+These will default to "no" for safety. Use [`--queue-include-external`](/docs/reference/cli/commands/run#queue-include-external) to explicitly include external dependencies.
+</Aside>

docs-starlight/src/data/flags/parallelism.mdx

@@ -6,4 +6,12 @@ env:
   - TG_PARALLELISM
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 Sets the maximum number of concurrent operations when running commands with `--all`. This helps control resource usage and API rate limits when working with multiple units.
+
+<Aside type="caution">
+When using `--parallelism` with provider caching, `terraform init` is always executed sequentially if OpenTofu/Terraform provider plugin cache is configured.
+
+To safely run concurrent operations with provider caching, enable the [Provider Cache Server](/docs/features/provider-cache-server/) instead.
+</Aside>

docs-starlight/src/data/flags/provider-cache-dir.mdx

@@ -6,6 +6,4 @@ env:
   - TG_PROVIDER_CACHE_DIR
 ---
 
-Specifies the directory where Terragrunt will store cached provider files. This flag is only used when [`provider-cache`](/docs/reference/cli/commands/run#provider-cache) is enabled.
-
-To learn more about how to use this flag, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+Specifies the directory where Terragrunt will store cached provider files. This flag is only used when the [Provider Cache Server](/docs/features/provider-cache-server) is enabled.

docs-starlight/src/data/flags/provider-cache-hostname.mdx

@@ -6,6 +6,4 @@ env:
   - TG_PROVIDER_CACHE_HOSTNAME
 ---
 
-Sets the hostname for connecting to the Provider Cache server. This flag is only used when [`provider-cache`](/docs/reference/cli/commands/run#provider-cache) is enabled.
-
-To learn more about how to use this flag, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+Sets the hostname for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/docs/features/provider-cache-server) is enabled.

docs-starlight/src/data/flags/provider-cache-port.mdx

@@ -6,6 +6,4 @@ env:
   - TG_PROVIDER_CACHE_PORT
 ---
 
-Specifies the port number for connecting to the Provider Cache server. This flag is only used when [`provider-cache`](/docs/reference/cli/commands/run#provider-cache) is enabled.
-
-To learn more about how to use this flag, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+Specifies the port number for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/docs/features/provider-cache-server) is enabled.

docs-starlight/src/data/flags/provider-cache-registry-names.mdx

@@ -6,6 +6,4 @@ env:
   - TG_PROVIDER_CACHE_REGISTRY_NAMES
 ---
 
-Specifies which provider registries should be cached by the Provider Cache server. This flag is only used when [`provider-cache`](/docs/reference/cli/commands/run#provider-cache) is enabled.
-
-To learn more about how to use this flag, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+Specifies which provider registries should be cached by the Provider Cache server. This flag is only used when the [Provider Cache Server](/docs/features/provider-cache-server) is enabled.

docs-starlight/src/data/flags/provider-cache-token.mdx

@@ -6,6 +6,4 @@ env:
   - TG_PROVIDER_CACHE_TOKEN
 ---
 
-Sets the authentication token for connecting to the Provider Cache server. This flag is only used when [`provider-cache`](/docs/reference/cli/commands/run#provider-cache-enable) is enabled.
-
-To learn more about how to use this flag, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+Sets the authentication token for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/docs/features/provider-cache-server) is enabled.

docs-starlight/src/data/flags/provider-cache.mdx

@@ -6,6 +6,12 @@ env:
   - TG_PROVIDER_CACHE
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 When enabled, Terragrunt will use its provider caching system to speed up provider downloads.
 
 For more information, see the [Provider Cache Server](/docs/features/provider-cache-server) feature documentation.
+
+<Aside type="note">
+The `tofu init` command is always executed sequentially if the provider plugin cache is used without the Provider Cache Server.
+</Aside>