Rules

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

Whenever we 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.

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

2. All the arguments preceding the final argument will usually be a noun.

   Exception

   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.

3. All flags will usually start with a noun.

   Exception

   The exception to this rule will be for negation as the flag will start with no/ non , as discussed below.

   If the flag is controlling a single configuration for Terragrunt, that configuration will be the name of the flag.

   Example

   --working-dir: Set the working directory configuration for Terragrunt.

   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.

   Example

   --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.

   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.

   Example

   • --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.

   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.

   Example

   --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.

4. Behavior on the same systems will always share the same stem.

   Example

   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.

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

   true will usually correspond to the default behavior of the flag, and false will correspond to the inverse.

   Exception

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

   For example, the 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 forward-tf-stdout).

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

   Example

   --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.

6. 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.

7. 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.

8. Flags that specifically control the behavior of OpenTofu/Terraform will be prefixed tf.

   Example

   --tf-path controls the path to the OpenTofu/Terraform binary.

9. 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.

   Example

   iam-assume-role-duration —> TG_IAM_ASSUME_ROLE_DURATION