Tutorial

Parse your first Terragrunt configuration

In about ten minutes, you will create a small TypeScript program that parses HCL, inspects its token tree, and prints diagnostics.

1. Create a project

   Start in an empty directory and install the parser, its TypeScript peer, and a development runner.

   npm init -y
   npm install tghclparser typescript
   npm install --save-dev tsx

2. Add a Terragrunt file

   Create terragrunt.hcl. This small configuration is valid enough to show structure and references.

   locals {
     environment = "development"
   }
   
   inputs = {
     environment = local.environment
     replicas    = 2
   }

3. Parse the document

   Create inspect.ts. A document belongs to a workspace, and both use file URIs rather than plain paths.

   import { readFile } from 'node:fs/promises';
   import { resolve } from 'node:path';
   import { pathToFileURL } from 'node:url';
   import { ParsedDocument, Workspace } from 'tghclparser';
   
   const filePath = resolve('terragrunt.hcl');
   const uri = pathToFileURL(filePath).toString();
   const content = await readFile(filePath, 'utf8');
   
   const workspace = new Workspace();
   workspace.setWorkspaceRoot(pathToFileURL(process.cwd()).toString());
   
   const document = new ParsedDocument(workspace, uri, content);
   await workspace.addDocument(document);
   
   console.log('diagnostics:', document.getDiagnostics());
   console.log('root tokens:', document.getTokens()[0]?.children.length ?? 0);

4. Run it

   npx tsx inspect.ts

   You should see an empty diagnostics array and a non-zero root-token count. You have parsed real HCL and attached it to workspace context.

5. Inspect the token tree

   Add this traversal after the existing output. Each token records its type, display value, source range, parent, and children.

   function printToken(token, depth = 0) {
     console.log(`${'  '.repeat(depth)}${token.type}: ${token.getDisplayText()}`);
     for (const child of token.children) printToken(child, depth + 1);
   }
   
   for (const token of document.getTokens()) printToken(token);

6. Introduce an error

   Remove the closing brace from the inputs object and run the script again. The diagnostics now contain source-positioned feedback. Restore the brace when you are done.

What you learned

You created a Workspace, parsed content into a ParsedDocument, read syntax and schema diagnostics, and traversed the token tree. Those same objects underpin completions, hovers, links, dependency graphs, and evaluation.

How-to guide

Replace terragrunt with tghclp

Run your existing Terragrunt configurations through tghclp instead, without changing them.

Install

npm install -g tghclparser

The package installs one executable, tghclp. It needs OpenTofu or Terraform on the path, the same as terragrunt does.

Substitute the command

Configurations are unchanged. Only the executable differs.

# before
terragrunt init
terragrunt plan
terragrunt run-all apply

# after
tghclp init
tghclp plan
tghclp apply --all

Note the last line: where terragrunt spells the whole-graph run run-all <command>, this spells it <command> --all.

Check a configuration before you rely on it

Validation is a separate command, so a configuration can be checked without running anything:

tghclp hcl validate --working-dir ./infrastructure

Where a configuration reads a file outside the workspace root — a deployment plan in a sibling checkout, say — name that directory. Terragrunt has no such boundary and will not have needed this.

tghclp --allow-path /srv/plans plan

Do not share a directory mid-migration

Each tool signs the files its generate blocks write, and refuses to overwrite a file bearing the other's signature. That protects hand-written files, but it means a working directory already generated into by terragrunt will refuse a tghclp run until those files are removed:

rm -f gen_*.tf gen_*.tfvars
tghclp init

Delete only files a generate block produces. Anything a person wrote is refused for the same reason and should stay.

Where behaviour is established

Compatibility is checked by running the same configuration through both executables and comparing what each produces — the generated files, the evaluated values, the refusals — rather than by reading the documentation and assuming agreement. A difference is a bug here, and worth reporting.

How-to guide

Validate Terragrunt HCL in CI

Fail a continuous-integration job when the repository contains syntax or schema diagnostics, and preserve machine-readable results.

Install and run validation

Install tghclparser as a development dependency so the validator version is pinned by your lockfile.

npm install --save-dev tghclparser
npx tghclp hcl validate --working-dir ./infrastructure

The command recursively discovers supported Terragrunt HCL files. It exits with status 1 when diagnostics exist and 0 when validation passes.

Add a GitHub Actions job

name: Validate Terragrunt HCL

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx tghclp hcl validate --working-dir ./infrastructure

Capture JSON diagnostics

Use --json when another tool will consume the result. Output is a JSON array only when diagnostics are present; always use the process exit status as the pass/fail signal.

npx tghclp hcl validate \
  --json \
  --working-dir ./infrastructure \
  > diagnostics.json

List only affected configurations

npx tghclp hcl validate \
  --show-config-path \
  --working-dir ./infrastructure

CI checklist

• Pin the package through package-lock.json.
• Point --working-dir at the repository subtree you intend to validate.
• Treat the exit status—not the presence of standard output—as authoritative.
• Upload JSON output as an artifact only when a later job needs it.

How-to guide

Build a workspace dependency graph

Discover the relationships between includes, dependencies, reads, and generated stack components.

Print DOT from the command line

For visualization tools such as Graphviz, generate a DOT graph directly.

npx tghclp dag graph --working-dir ./infrastructure > graph.dot
dot -Tsvg graph.dot -o graph.svg

To graph discovered configurations through list, enable dependency edges explicitly:

npx tghclp list \
  --format=dot \
  --dependencies \
  --working-dir ./infrastructure

Build the graph in TypeScript

import { pathToFileURL } from 'node:url';
import { Workspace } from 'tghclparser';

const workspace = new Workspace();
workspace.setWorkspaceRoot(pathToFileURL('/repo/infrastructure').toString());

const root = await workspace.refreshDependencyTree();

await root?.breadthFirstTraversal(async (node, depth) => {
  console.log(`${'  '.repeat(depth)}${node.type}: ${node.name}`);
  return true;
});

Query one configuration

Use a file URI when asking for dependencies or dependents.

const unitUri = pathToFileURL(
  '/repo/infrastructure/app/terragrunt.hcl'
).toString();

const dependencies = await workspace.getDependencies(unitUri);
const dependents = await workspace.getDependents(unitUri);

console.log(dependencies.map((config) => config.targetPath));
console.log(dependents.map((config) => config.targetPath));

How-to guide

Add language features to an editor

Turn an open Terragrunt file into diagnostics, completions, hover content, and navigable document links.

Create and register a document

import { pathToFileURL } from 'node:url';
import { ParsedDocument, Workspace } from 'tghclparser';

const rootUri = pathToFileURL('/repo/infrastructure').toString();
const fileUri = pathToFileURL('/repo/infrastructure/app/terragrunt.hcl').toString();

const workspace = new Workspace();
workspace.setWorkspaceRoot(rootUri);

const document = new ParsedDocument(workspace, fileUri, sourceText);
await workspace.addDocument(document);

Read language-service results

Positions are zero-based LSP positions: the first line and first character are both 0.

const position = { line: 8, character: 17 };

const diagnostics = document.getDiagnostics();
const completions = await document.getCompletionsAtPosition(position);
const hover = await document.getHoverInfo(position);
const links = await document.getLinks();
const token = document.findTokenAtPosition(position);

Handle edits

Update the document content, then re-add it so the workspace rebuilds relationships owned by that document.

document.setContent(updatedSourceText);
await workspace.addDocument(document);

publishDiagnostics(fileUri, document.getDiagnostics());

Handle close events

workspace.removeDocument(fileUri);

Reference

Command line

The tghclp executable validates, discovers, formats, evaluates, scaffolds, and orchestrates Terragrunt configurations. It is a drop-in replacement for the terragrunt command.

Synopsis

tghclp [global options] <command> [options]

Terragrunt equivalents

Each command below does what the terragrunt command beside it does. Substituting one executable for the other requires no change to a configuration.

Validation options

Discovery options

Global options

Terragrunt renamed those flags when it dropped the prefix, and scripts still pass the old names, so both spellings are accepted. Only flags this honours are aliased: a legacy flag with no equivalent here — --terragrunt-download-dir, say — is refused rather than accepted and quietly dropped, because a caller that believes a flag took effect is worse off than one told it did not.

The workspace boundary comes from this tool's other life as a language server, where a configuration is opened before anyone has vouched for it. Terragrunt has no such boundary, so a layout it accepts can be one this refuses — a deployment plan kept in a sibling checkout, for instance. Name each such directory rather than widening the root, which would have to reach an ancestor broad enough to stop being a boundary at all.

tghclp --allow-path /srv/plans init

Execution behavior

run and OpenTofu shortcut commands validate the selected configuration before starting the executable. Use --tf-path <path> to select a binary; the default is tofu, or the value of TG_TF_PATH / TERRAGRUNT_TFPATH.

tghclp run --working-dir ./infrastructure/app -- plan
tghclp plan --working-dir ./infrastructure/app
tghclp apply --all --working-dir ./infrastructure
tghclp run --tf-path terraform --working-dir ./app -- apply

The executable is spawned without a shell. Arguments are passed directly.

Generated files

A generate block writes its file with a signature line naming this tool. if_exists = "overwrite_terragrunt" then means what it says — overwrite a file this tool generated — and a file without that signature is refused rather than destroyed.

The signature is deliberately not terragrunt's own. Each tool refuses a file bearing the other's mark, so a directory generated into by one is not silently taken over by the other, and the message says which tool wrote what.

Reference

JavaScript API

Public exports from the tghclparser package root. The package provides ESM, CommonJS, and TypeScript declarations.

Core classes

const evaluator = new ConfigEvaluator({
  environmentVariables: process.env,
  workspaceTrusted: true,
  terraformCommand: 'plan',
  terraformCliArgs: []
});

The resolveDependency(request) option reads a dependency's outputs. The evaluator finds the dependency block in the unit and the configurations merged into it, the way Terragrunt merges them, evaluates config_path and the mocks where they are written, and passes a DependencyRequest: { name, unitPath, declaredIn, targetConfigPath, targetDir, mockOutputs?, mockOutputsAllowedTerraformCommands? }, with config_path resolved against the unit's directory. The resolver resolves to { outputs: … }, or to undefined when the dependency has no outputs yet, which evaluation reports as unresolved. A dependency declared nowhere the unit merges is a fault the evaluator reports itself. Each dependency is resolved once per evaluation.

Lookup methods include getFileKind, getRootBlockDefinitions, getRootAttributeDefinitions, getBlockDefinition, getAllBlockTemplates, getAllFunctions, and getFunctionDefinition. Snippet helpers and value-validation methods are also public.

Register implementations with registerFunction, operations with registerOperation, or a namespaced group with registerFunctionGroup. Duplicate names throw.

Utility exports

Primary types

RuntimeValue preserves an explicit value type. Objects and blocks contain Map<string, RuntimeValue>; arrays contain nested runtime values. TerragruntConfig records a configuration's URI, content, incoming and outgoing relationships, source and target paths, dependency type, and optional outputs.

Reference

Supported files

File names select a schema. The parser accepts general HCL syntax, while diagnostics and completions follow the Terragrunt file kind.

Discovery

The CLI's find, list, and graph discovery commands look specifically for terragrunt.hcl and terragrunt.stack.hcl. Validation recognizes the broader supported filename set.

Discovery skips .git, .scrap, .terraform, .terragrunt-cache, .terragrunt-stack, .trash, and node_modules. With --no-hidden, it skips all hidden directories.

Language regime

Version 1 follows the current Terragrunt language regime. Removed or deprecated compatibility syntax is intentionally not accepted. The schema covers unit configuration, stack components, autoincludes, features, excludes, error policies, catalogs, IaC engines, CAS source controls, and Terragrunt functions.

Explanation

How the toolkit fits together

tghclparser separates syntax, language knowledge, workspace context, and semantic evaluation because each answers a different question.

Four layers, four questions

Why tokens sit between syntax and features

The raw parser AST closely follows grammar rules. A ParsedDocument also builds a navigable Token tree. Tokens normalize the shapes that completions, hovers, links, diagnostics, and reference resolution need while preserving parent/child relationships and source ranges.

This keeps editor providers from each having to reinterpret raw parser nodes. It also gives callers a stable vocabulary such as block, attribute, reference, function_call, and interpolation.

Why a document needs a workspace

Terragrunt configuration is rarely meaningful in isolation. An include can expose locals, a dependency can expose state outputs, a stack can declare generated component targets, and a function can read another configuration. The workspace owns that cross-file context.

A document can still report local syntax and schema diagnostics immediately. Registering it with a workspace adds the context needed for reference-aware results and graph queries.

Why runtime values keep their types

Evaluation does not collapse everything into plain JavaScript. RuntimeValue<T> carries an explicit Terragrunt value type, and nested collections contain more runtime values. This allows providers to retain type knowledge, sensitive wrappers, and origin information while computing results. Convert to plain values only at an application boundary with runtimeValueToPlain.

Language service versus execution

Parsing and most editor assistance are observational: they analyze text. Semantic evaluation can read workspace files and invoke selected functions. Command execution goes further by starting an OpenTofu, Terraform, or explicitly requested external program. Those capabilities are kept behind separate APIs and trust checks.

Explanation

Trust and evaluation

Parsing text is different from evaluating a repository. The trust boundary makes that distinction explicit.

Parsing is local analysis

Constructing a ParsedDocument parses its supplied string, creates tokens, and computes immediate diagnostics. It does not need permission to execute arbitrary programs.

Evaluation can observe the workspace

Terragrunt semantics include functions that read files, find parent configurations, inspect environment variables, and derive paths. Accurate evaluation therefore needs a filesystem context. ConfigEvaluator refuses semantic evaluation unless workspaceTrusted is explicitly true.

Paths stay inside the workspace root

Trusted file access resolves real paths and rejects targets outside the workspace root. Resolving real paths is important because a path that looks internal can escape through a symbolic link.

Function operations separate data from capabilities

Function evaluation uses named operations. Arguments travel through a serializable dry context; live services such as filesystem access or command execution travel through a wet context. This boundary makes capability-bearing context visible instead of smuggling it into ordinary values.

Remote modules reach the network

A unit whose terraform { source } names a registry module can have that module fetched, so its variables drive input completion, hover and checks. This is the one place the language service contacts a network, and it does so only when the caller asks: Workspace.configureRemoteModules takes a policy that must be both enabled and trusted, and an approveHost callback that is asked before the first contact with each registry or git host. A workspace that never calls it leaves remote sources alone.

A registry token is sent to its registry host alone, over TLS. Every host a request reaches, including one a registry redirects to, must be named rather than addressed and must resolve outside the loopback and link-local ranges. Git runs without a shell, with prompts disabled and the repository URL kept off its command line. Only the top-level .tf files of a module are kept, read from the object store or the archive stream without unpacking anything, into an owner-only per-user cache.

The CLI does not invoke a shell

run and exec spawn the selected executable with an argument array and shell: false. Shell operators in an argument are not interpreted as shell syntax. This removes a common command-injection surface, although callers must still choose trusted executables and arguments.

Recommended integration policy

• Allow parsing and local diagnostics before workspace trust.
• Gate semantic evaluation and workspace file reads on explicit trust.
• Keep the workspace root as narrow as practical.
• Pass environment variables intentionally; they are part of evaluation input.
• Require a separate user action before executing infrastructure commands.
• Fetch remote modules only in a trusted workspace, and ask the user before the first contact with each host.