Terragrunt HCL Language Server

Rich, context-aware editor support for the Terragrunt 1.x configuration model — completions, validation, hover docs, clickable navigation, and a visual lineage graph.

This is a community-supported project. It is not affiliated with Gruntworks, Inc. or the Terragrunt project, but it tracks the official Terragrunt documentation closely and follows the current 1.x regime.

Install Terragrunt Language Server from the VS Code Marketplace, or build the extension from this repository.

Features

• Context-aware completions for blocks, attributes, functions, locals, dependencies, includes, features, values, units, and stacks
• File-kind-aware validation that knows the difference between a unit, an explicit stack, a values file, and an autoinclude — with current-regime diagnostics that flag removed and deprecated syntax
• Hover documentation and clickable document links for includes, dependencies, and read files
• Go to definition for local.*, include.<name>.locals.*, include.<name>.inputs.*, and dependency.<name>.* references
• Evaluated values on hover, with the expressions that have one underlined — see Settings
• Show Terragrunt Lineage Graph — a visual, interactive graph of the whole workspace covering includes, dependencies, units, nested stacks, and reading lineage, with dependency outputs surfaced from state
• Formatting into the layout terragrunt hcl format produces, with nothing else to install — see Formatting
• Remote module sources — a registry module's variables drive completion, hover and checks in inputs, as a local module's do — see Remote module sources
• Syntax highlighting for Terragrunt blocks, attributes, references, and functions

The lineage graph opens with the first two levels visible, provides filter and expand/collapse controls, preserves the filter between views, uses full-row targets, and reports loading and empty states explicitly. Open is shown only for files inside the active workspace.

What it understands

• terragrunt.hcl and named shared unit configurations such as root.hcl
• terragrunt.stack.hcl explicit stacks
• terragrunt.values.hcl generated stack values
• terragrunt.autoinclude.hcl and terragrunt.autoinclude.stack.hcl

Getting started

1. Install the extension from the VS Code Marketplace.
2. Open any .hcl file in a Terragrunt workspace — completions, validation, hover, and links work immediately.
3. Run Show Terragrunt Lineage Graph from the Command Palette while an HCL editor is active to see how the units in your workspace include, depend on, and read each other.

Formatting

Format Document and format on save lay a file out exactly as terragrunt hcl format does: two-space indentation, single spaces between tokens, and the equals signs and trailing comments of consecutive lines aligned. Only whitespace changes.

The formatter is built in, so neither Terragrunt nor OpenTofu needs to be installed, and it works in Restricted Mode. A file with a syntax error is not changed; the error is among its problems and in the tg-hcl-lsp output.

Remote module sources

A unit whose terraform { source } is a local path has its inputs completed, documented and checked against the module's variables. A registry source (tfr:///namespace/name/provider?version=…) gets the same once it is fetched. Fetching contacts a network, so it waits for your answer about each host.

• Trust: nothing is fetched in Restricted Mode; the source has a hint saying so.
• Hosts: you are asked before the first contact with each registry or git host: Allow or Deny for this session, or Always Allow or Always Deny. Approving a registry covers the hosts it sends downloads to. A question that has left the screen waits in the notification centre, under the bell in the status bar. A prompt closed without an answer is asked again next time. A denied host's module has a problem on source with a quick fix that asks again; Terragrunt: Forget Module Host Answer does the same for a host you picked Always Allow or Always Deny for, and Terragrunt: Retry Remote Module Fetches asks again about every host denied this session.
• Which registry: tfr:/// means what it means to Terragrunt: TG_TF_DEFAULT_REGISTRY_HOST when it is set, else the registry of the binary Terragrunt would run, which is registry.terraform.io for terraform and registry.opentofu.org for anything else.
• What is fetched: the module's top-level .tf files, from the git repository or archive the registry points to, into a per-user cache keyed by version, so each version is fetched once. Terragrunt: Clear Remote Module Cache empties it and fetches open units' modules again.
• Registry tokens: Terragrunt: Set Registry Token saves a token for a host in the system keychain, through VS Code's secret storage; it is never written to settings. Terragrunt: Remove Registry Token deletes one. When a registry refuses a fetch for want of a token, the problem on source offers a quick fix that asks for one. A token is read only when its host is about to be contacted, and sent to that host alone. Without one, the token Terraform would use is found as Terraform finds it: TF_TOKEN_<host>, then credentials blocks in ~/.terraformrc or ~/.terraform.d, then TG_TF_REGISTRY_TOKEN for private registries.
• Git: modules served from git need git 2.31 or newer on PATH, and use git's own credential helpers and ssh agent; the extension holds no git credentials.

Settings

terragrunt.evaluatedValues.underline

Hovering an expression shows the value it evaluates to. A dotted underline marks the expressions that have one, and this setting decides which of those are drawn.

Terragrunt 1.x first

Root configurations should use named includes and explicit filenames:

include "root" {
  path = find_in_parent_folders("root.hcl")
}

Explicit stacks are recognized through terragrunt.stack.hcl:

unit "network" {
  source = "../catalog/network"
  path   = "network"
}

unit "app" {
  source = "../catalog/app"
  path   = "app"

  autoinclude {
    dependency "network" {
      config_path = unit.network.path
    }
  }
}

The implementation tracks the official Terragrunt blocks, attributes, functions, and stacks documentation.

Development

Install dependencies and create the extension bundle:

npm ci
npm run webpack

For continuous development, rebuild on source changes:

npm run watch

Running the tests

The tests run in a real VS Code, downloaded into .vscode-test on the first run. They bundle the extension, open the configurations in tests/fixtures and check what the language server returns for them:

npm run test:extension-host

Run from a terminal inside VS Code, ELECTRON_RUN_AS_NODE is set and the test VS Code fails to start. Unset it first with env -u ELECTRON_RUN_AS_NODE npm run test:extension-host. Logs from a run are in .vscode-test/user-data/logs.

Testing against a local tghclparser

The server depends on the published tghclparser package. To build against a local checkout beside this repository instead, point node_modules at it:

cd node_modules
rm -rf tghclparser
ln -s ../../tghclparser tghclparser

Build the parser first (npm run build in its checkout), since webpack bundles its dist/index.cjs rather than its sources. Rebuild it after any parser change.

To go back to the published version:

npm ci

Launch the repository as a VS Code Extension Development Host after bundling it. Test completion, diagnostics, hover, and document links with current Terragrunt HCL files, or open the lineage graph from the Command Palette while an HCL editor is active.

Contributions are welcome — bug reports, feature ideas, and pull requests all help. The parsing and language-service engine is developed separately in tghclparser and published as a standalone npm package, so fixes there flow into the extension.

Thanks

Thanks to everyone who contributed feedback, reported issues, submitted pull requests, tested changes, or otherwise helped improve the project:

• X-Guardian
• and-win
• rtizzy
• lucalooz
• gsouf
• jonath92
• mateothegreat
• prestonr83
• jimweller
• AntonSedna
• vizorich

License

MIT. See LICENSE.

This is a community-supported project and is not affiliated with Gruntworks, Inc. or the Terragrunt project. You can support the project by starring it on GitHub or contributing to it. Pull requests are welcome.