CLI Rules - Terragrunt

import { Aside, Badge, LinkCard } from '@astrojs/starlight/components';

These are the rules that Terragrunt maintainers endeavor to follow when working on the CLI.

Whenever maintainers break these rules, that is a bug and should be reported. The maintainers will either fix the behavior, or update the rules to reflect the reason for the discrepancy.

In addition, if you find that a certain pattern that's reliably followed in the CLI is not documented here, please let us know so we can update this document to encourage consistency.

The final argument to a Terragrunt command will always be a verb.

All the arguments preceding the final argument will <Badge text="usually" variant="caution" /> be a noun.

      The exceptions to this rule are commands like `terragrunt run`, as these will frequently have two **verbs** in sequence (e.g. `terragrunt run plan`).

      This is an exception to the rule because it is exceptional behavior. The end of Terragrunt’s responsibility (from a CLI design perspective) is to process the `run` command, so what follows is not subject to the rules dictated here.

</details>

All flags will <Badge text="usually" variant="caution" /> start with a noun.
<details> <summary><Badge text="Exception" variant="caution" /></summary>
```
 The exception to this rule will be for negation as the flag will start with `no`/ `non` , as discussed below.
```
</details>
If the flag is controlling a single configuration for Terragrunt, that configuration will be the name of the flag.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 `--working-dir`: Set the `working directory` configuration for Terragrunt.
```
</details>
If a Terragrunt system can be controlled entirely by referencing the name of the system, or the flag can control high level behavior of Terragrunt on its own, that will be the name of the flag.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 `--provider-cache`: The system is the `provider cache` server. The Provider Cache Server be enabled if this flag is set.

 For brevity, prefer this to flags like `--provider-cache-enable`.
```
</details>
If a configuration is being set for a system, another noun will follow the name of the system after a dash. The flag will accept a parameter that sets the configuration for that system.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 - `--log-level`: The system is `log`, the `level` is the configuration.

 - `--provider-cache-dir`: The system is the `provider cache` server. The directory is the configuration.
```
</details>
If an operation will be performed on a system, a verb will follow. If necessary, a noun will follow the verb to indicate what the parameter for that flag corresponds to, or the setting it controls for the operation.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 `--queue-include-unit` - The system is the runner `queue`. The operation being performed to that system is `include`. The parameter of `unit` indicates that the parameter to the flag will be a `unit` being `included` in the `queue`.
```
</details>
Behavior on the same systems will always share the same stem.
<details> <summary><Badge text="Example" variant="note" /></summary> All flags that have to do with the Terragrunt Provider Cache Server will start with `provider-cache`.
```
 A user looking through the flags available in Terragrunt sorted in alphabetical order will find them right next to each other.
```
</details>

All boolean flags will accept an optional parameter of true or false .

true will <Badge text="usually" variant="caution" /> correspond to the default behavior of the flag, and false will correspond to the inverse.

 The exception to this rule is when the default behavior of a flag changes.

 For example, the [terragrunt-include-module-prefix](https://docs.terragrunt.com/reference/cli-options/#terragrunt-include-module-prefix) flag was previously opt-in, but users were better served with the behavior being opt-out. To preserve backwards compatibility until the next release, the flag remained, but to use it, users had to set it via `--terragrunt-include-module-prefix=false`.

 In this scenario, whenever applicable, a different flag will be made available that does obey this rule (like [tf-forward-stdout](https://docs.terragrunt.com/reference/cli-options/#tf-forward-stdout)).

</details>

When a flag prevents something from happening that Terragrunt would do by default, it will be proceeded by the prefix no/ non.

 `--no-color` has a default value of `true`, and setting it to `false` will make it so that the behavior of not setting the flag is active (Terragrunt will emit colorful output).

 The alternative would be to have a `--color` flag, and using that flag to disable color would require that they do something like `--color=false`.

 This would violate the rule that the default behavior of the flag wouldn’t change anything, as Terragrunt emits color by default.

</details>

Commands and flags will always be backwards compatible until the next major release of Terragrunt.

This includes instances where behavior violates one of the other rules listed here.
If naming a command or flag following these rules would make it harder to understand or longer than it needs to be, the exception will be allowed and documented.
Flags that specifically control the behavior of OpenTofu/Terraform will be prefixed tf.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 `--tf-path` controls the path to the OpenTofu/Terraform binary.
```
</details>
Every flag will have at least one corresponding environment variable that is exactly the same text as the flag, but converted to SHOUTY_SNAKE_CASE instead of kebab-case, and prefixed with TG_.

When more than one environment variable controls a flag, it will be to support backwards compatibility.
<details> <summary><Badge text="Example" variant="note" /></summary>
```
 `iam-assume-role-duration` —> `TG_IAM_ASSUME_ROLE_DURATION`
```
</details>
When a setting can be provided by both a flag and configuration, resolution follows a fixed order of precedence, most specific first:

CLI argument → environment variable → configuration → built-in default.

An explicitly set flag always wins over a configuration value. Configuration overrides only Terragrunt's built-in default for that setting, never a value the user set explicitly on the flag (or its environment variable).
<details> <summary><Badge text="Example" variant="note" /></summary>
```
An explicit `--download-dir` takes precedence over `download_dir` in the configuration. The `download_dir` attribute applies only when `--download-dir` is left at its default, filling in that default rather than overriding the flag.
```
</details>