fix: Adding missing flags to the hcl command

[yhakbar]

Description

Fixes #4907

TODOs

Read the Gruntwork contribution guidelines.

• I authored this code entirely myself
• I am submitting code based on open source software (e.g. MIT, MPL-2.0, Apache)]
• I am adding or upgrading a dependency or adapted code and confirm it has a compatible open source license
• Update the docs.
• Run the relevant tests successfully, including pre-commit checks.
• Include release notes. If this PR is backward incompatible, include a migration guide.

Release Notes (draft)

Added / Removed / Updated [X].

Migration Guide

Summary by CodeRabbit

• New Features

  • Added queue control flags to the HCL validate command.
  • Unified TF/OpenTofu binary path flag across commands with consistent behavior and env var support.

• Documentation

  • Help output updated to reflect the unified TF path flag.

• Refactor

  • Standardized flag definitions across commands for consistent naming and behavior.
  • Maintained compatibility with deprecated environment variables.

• Tests

  • Updated tests to validate behavior against the shared flag definitions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
terragrunt-docs	Ready	Preview	Comment	Oct 7, 2025 8:42pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Centralizes TF path and queue-related CLI flags into a new shared module and updates commands/tests to consume these shared definitions. Removes a local TF path flag factory, adjusts function signatures to drop a prefix parameter, and wires shared flags into hcl validate and run command flows.

Changes

Cohort / File(s)	Summary
Shared flag module cli/flags/shared/shared.go	Introduces shared flag constructors/constants: TFPath and queue-scoping flags; adds NewTFPathFlag(opts) and NewQueueFlags(opts, prefix) and maps them to TerragruntOptions with env/deprecated env support.
HCL validate CLI integration cli/commands/hcl/validate/cli.go	Updates NewFlags signature to remove prefix; computes internal prefix; integrates shared.NewTFPathFlag and shared.NewQueueFlags; adjusts NewCommand to call NewFlags(opts).
Run command flag wiring cli/commands/run/flags.go, cli/commands/run/help.go	Replaces local NewTFPathFlag with shared.NewTFPathFlag; adds shared.NewQueueFlags in flags.go; minor comment fix; updates help to new TF path flag constructor signature.
Tests update cli/app_test.go	Switches references of queue flag names from run package to shared package.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant CLI as terragrunt
  participant Cmd as hcl validate command
  participant Shared as flags/shared
  participant Opts as TerragruntOptions
  participant Exec as Executor

  User->>CLI: terragrunt hcl validate [--tf-path ... --queue-...]
  CLI->>Cmd: Initialize command
  Cmd->>Shared: NewTFPathFlag(opts)\nNewQueueFlags(opts, prefix)
  Shared-->>Opts: Bind parsed values (TFPath, include/exclude, units, etc.)
  Cmd->>Exec: Run validate with Opts (tf-path honored, queue scope applied)
  Exec-->>User: Validation result
  note over Shared,Exec: New/centralized flag constructors drive option wiring

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix: Fixing CLI option for --queue-include-unit-reading #3869 — Updates docs for queue-include-units-reading; related to introducing and wiring this flag in shared flags.
• chore: Remove legacy terragrunt flags #4650 — Refactors CLI flag handling and constants similar to this centralization; overlapping flag changes.
• fix [#4613]: register additional flags in the DAG graph subcommand #4726 — Registers queue flags for DAG/graph subcommand; aligns with moving queue flags to shared and reusing them.

Suggested reviewers

• denis256
• levkohimins

Pre-merge checks and finishing touches

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues Check	⚠️ Warning	While the PR integrates the shared TF path and queue flags into the hcl validate command, it does not apply the same updates to the hcl fmt subcommand, so the flags will not be honored for formatting operations and legacy run-all validate-inputs remains incomplete.	Extend the shared.NewTFPathFlag and shared.NewQueueFlags integration to the hcl fmt command and verify that queue-include-dir and tf-path flags are honored in both fmt and legacy run-all validate-inputs flows to fully satisfy issue #4907.
Description Check	⚠️ Warning	The description only includes a Fixes reference and template placeholders but lacks any summary of the specific changes introduced by this PR, actual release notes content, and a migration guide, leaving the required sections incomplete.	Provide a concise summary of the changes made by this PR in the Description section, fill in the Release Notes with the flags added, and include a Migration Guide if there are any backward-incompatible updates.
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly and concisely describes the main change, indicating that missing flags are being added to the hcl command without including extraneous details or file lists.
Out of Scope Changes Check	✅ Passed	All modifications are directly related to consolidating flag definitions into a shared module and integrating those flags into the hcl and run commands, which aligns with the objectives of restoring --tf-path and queue-scoping flags.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/adding-missing-flags-to-hcl

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b32ea2e and 82eb10f.

📒 Files selected for processing (5)

• cli/app_test.go (3 hunks)
• cli/commands/hcl/validate/cli.go (2 hunks)
• cli/commands/run/flags.go (4 hunks)
• cli/commands/run/help.go (2 hunks)
• cli/flags/shared/shared.go (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.go

⚙️ CodeRabbit configuration file

Review the Go code for quality and correctness. Make sure that the Go code follows best practices, is performant, and is easy to understand and maintain.

Files:

• cli/flags/shared/shared.go
• cli/commands/hcl/validate/cli.go
• cli/commands/run/help.go
• cli/app_test.go
• cli/commands/run/flags.go

🧠 Learnings (2)

📚 Learning: 2025-04-17T13:02:28.098Z

Learnt from: yhakbar
PR: gruntwork-io/terragrunt#4169
File: cli/commands/hcl/validate/cli.go:29-60
Timestamp: 2025-04-17T13:02:28.098Z
Learning: Avoid shadowing imported packages with local variables in Go code, such as using a variable named `flags` when the `github.com/gruntwork-io/terragrunt/cli/flags` package is imported. Use more specific variable names like `flagSet` instead.

Applied to files:

• cli/commands/hcl/validate/cli.go
• cli/commands/run/help.go
• cli/app_test.go
• cli/commands/run/flags.go

📚 Learning: 2025-02-10T13:36:19.542Z

Learnt from: levkohimins
PR: gruntwork-io/terragrunt#3723
File: cli/commands/stack/action.go:160-160
Timestamp: 2025-02-10T13:36:19.542Z
Learning: The project uses a custom error package `github.com/gruntwork-io/terragrunt/internal/errors` which provides similar functionality to `fmt.Errorf` but includes stack traces. Prefer using this package's error functions (e.g., `errors.Errorf`, `errors.New`) over the standard library's error handling.

Applied to files:

• cli/commands/run/help.go

🧬 Code graph analysis (5)

cli/flags/shared/shared.go (7)

options/options.go (1)

• TerragruntOptions (100-332)

cli/flags/deprecated_flag.go (1)

• StrictControlsByGlobalFlags (104-108)

cli/flags/flag.go (1)

• NewFlag (28-41)

internal/cli/generic_flag.go (1)

• GenericFlag (19-48)

cli/flags/flag_opts.go (1)

• WithDeprecatedEnvVars (103-114)

internal/cli/bool_flag.go (1)

• BoolFlag (13-49)

internal/cli/slice_flag.go (1)

• SliceFlag (23-58)

cli/commands/hcl/validate/cli.go (1)

cli/flags/shared/shared.go (2)

• NewTFPathFlag (31-49)
• NewQueueFlags (52-148)

cli/commands/run/help.go (1)

cli/flags/shared/shared.go (1)

• NewTFPathFlag (31-49)

cli/app_test.go (3)

cli/flags/shared/shared.go (3)

• QueueIncludeExternalFlagName (25-25)
• QueueIgnoreErrorsFlagName (19-19)
• QueueExcludeExternalFlagName (21-21)

util/file.go (1)

• JoinPath (626-628)

config/config.go (1)

• DefaultTerragruntConfigPath (47-47)

cli/commands/run/flags.go (1)

cli/flags/shared/shared.go (2)

• NewTFPathFlag (31-49)
• NewQueueFlags (52-148)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Pull Request has non-contributor approval

🔇 Additional comments (10)

cli/commands/run/flags.go (2)

9-9: LGTM! Shared flag integration looks correct.

The changes successfully centralize TF path and queue flag definitions into the shared module:

• The import of the shared package enables access to the centralized flag constructors.
• Line 147 correctly replaces the local two-argument NewTFPathFlag(opts, prefix) with the shared single-argument shared.NewTFPathFlag(opts).
• Line 519 integrates queue flags via shared.NewQueueFlags(opts, prefix), which aligns with the PR objective to restore queue-scoping flags for hcl commands.

The shared flag constructors handle prefix management internally, so the signature change from two to one argument is expected and correct.

Also applies to: 147-147, 519-519

---

118-118: Nice catch on the typo!

The comment correction from graph/-grpah to graph/-graph improves clarity.

cli/commands/hcl/validate/cli.go (2)

8-8: Signature simplification looks correct.

The NewFlags function signature has been simplified to remove the prefix parameter:

• Line 8 adds the import for the shared package.
• Line 23 removes the prefix flags.Prefix parameter.
• Line 24 now constructs tgPrefix directly from a static value instead of deriving it from the provided prefix.

This change is consistent with the shift to using shared flag constructors that handle prefix management internally. The single call site at line 87 has been updated accordingly.

Also applies to: 23-24

---

75-78: Integration with shared flags restores missing functionality.

Lines 75-78 add the missing TF path and queue flags:

• Line 75: shared.NewTFPathFlag(opts) ensures --tf-path is available to control which binary (terraform/tofu) is used.
• Line 78: shared.NewQueueFlags(opts, nil) adds queue-scoping flags like --queue-include-dir and --queue-include-units-reading.

Passing nil as the prefix to NewQueueFlags is appropriate here, as the shared function will prepend the standard TgPrefix internally. This directly addresses the PR objective to restore these flags for hcl subcommands.

cli/flags/shared/shared.go (4)

1-5: Package documentation is clear but notes underutilization.

The package comment correctly describes the purpose and acknowledges that the package is underutilized, indicating that further refactoring is needed to migrate more shared flags here. This is good context for future maintainers.

---

13-28: Flag name constants follow consistent naming convention.

The constants use a clear and consistent pattern: [Category][Purpose]FlagName. All queue-related flags are properly prefixed with Queue, making them easy to identify and group.

---

30-49: TF path flag implementation is correct.

The NewTFPathFlag function:

• Properly sets both opts.TFPath and opts.TFPathExplicitlySet (line 42-43), which is crucial for distinguishing between default and user-specified paths.
• Correctly wires environment variables with the tgPrefix (line 39).
• Includes deprecated environment variable support for TERRAGRUNT_TFPATH (line 47).
• Has appropriate usage text (line 40).

This addresses the PR objective to ensure --tf-path is honored by hcl subcommands.

---

51-148: Queue flags implementation is comprehensive and correct.

The NewQueueFlags function provides all necessary queue-control flags:

• Each flag is properly mapped to its corresponding field in opts (e.g., QueueIgnoreErrorsFlagName → opts.IgnoreDependencyErrors).
• Environment variable wiring uses tgPrefix.EnvVars() consistently.
• Deprecated environment variables (with TERRAGRUNT_ prefix) are properly registered via flags.WithDeprecatedEnvVars.
• The prefix.Prepend() pattern (line 53) allows callers to add additional prefix layers while maintaining the base TgPrefix.
• Usage strings clearly describe each flag's purpose.
• Appropriate flag types are used: BoolFlag for toggles, GenericFlag[string] for single values, and SliceFlag[string] for multiple values.

This directly addresses the PR objective to restore queue-scoping flags like --queue-include-dir and --queue-include-units-reading for hcl subcommands.

cli/app_test.go (1)

18-18: Test updates correctly reference shared flag names.

The test file has been updated to import and use flag name constants from the shared package:

• Line 18 adds the import for github.com/gruntwork-io/terragrunt/cli/flags/shared.
• Lines 81, 106, and 111 now reference shared.QueueIncludeExternalFlagName, shared.QueueIgnoreErrorsFlagName, and shared.QueueExcludeExternalFlagName respectively.

These changes ensure the tests validate behavior with the centralized flag definitions, maintaining consistency across the codebase.

Also applies to: 81-81, 106-106, 111-111

cli/commands/run/help.go (1)

8-8: TF path flag parsing updated correctly for help display.

The changes align with the shared flag refactoring:

• Line 8 adds the import for the shared package.
• Line 34 updates the call from NewTFPathFlag(opts, nil) to shared.NewTFPathFlag(opts), matching the new single-argument signature.

This ensures that the --tf-path flag is correctly parsed from arguments when displaying Terraform/OpenTofu help, maintaining the intended behavior while using the centralized flag constructor.

Also applies to: 34-34

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}