Note: This is a public document referenced by the RFC #3445. All feedback and status updates for this RFC will take place there.

Summary

Change default assumptions about the Terragrunt CLI so that:

• The terragrunt prefix is removed from all flags.
• Arguments are not sent to tofu / terraform by default.
• A new run command is introduced in to the CLI that will also handle the current responsibilities of run-all and graph.
• A new exec command is introduced into the CLI.
• A new backend command is introduced to support users in interacting with backends.
• New find and list commands are introduced to support users in finding unit configurations.
• Infrequently used commands are reorganized into a structure that makes it easier to find them.

Motivation

Terragrunt has required that some design decisions be made in order to be flexible enough to handle being used as a wrapper for other tools like Terraform and OpenTofu without having users run into bugs from the ordering of CLI flags or collisions on shared flags, etc.

As a consequence, a couple issues have arisen:

1. The flags are verbose (they are all prefixed by terragrunt, which is 10 additional characters, 11 with the extra -).
2. All the flags that are used during execution of OpenTofu/Terraform commands have to be globally available.
   • The help displayed for Terragrunt as of 0.66.3
3. Users receive bad error messages when they use invalid commands.
   • Error from Terragrunt
4. Default behavior of Terragrunt can be surprising.
   1. Misspelling a Terragrunt command will throw an error that Terraform doesn’t have a command because any command that is not a known Terragrunt command is forwarded to Tofu/Terraform.
   2. Remote state resource creation is attempted by default without opt-in via environment variable / CLI input.
5. Idiomatic usage of Terragrunt can lead to unfortunate side-effects.
   1. Directory filenames cannot be adjusted, as they impact the path to backend state files, and that requires migrating state.
6. The top level commands for Terragrunt can be confusing to inexperienced folks:
   • Commands

Proposal