catalog

Usage

Launch a Terminal User Interface (TUI) to browse and use OpenTofu/Terraform modules.

Examples

Start up a catalog using the configurations discovered in a parent Terragrunt configuration.

terragrunt catalog

Explicitly indicate the name of the root configuration being discovered.

terragrunt catalog --root-file-name root.hcl

terragrunt catalog [repo-url] [options]

For more information on how the catalog works, see the dedicated catalog documentation.

Flags

--format

Format the catalog as specified. Supported values (tui, jsonl, md). Default: tui when stdin and stdout are terminals, jsonl otherwise.

Experimental

This flag is gated behind the catalog-format experiment. Enable it with --experiment=catalog-format or TG_EXPERIMENT=catalog-format.

Formats

• tui renders the catalog as an interactive Terminal User Interface.
• jsonl writes one JSON object per line to standard output, so a script can read the catalog where a terminal user interface cannot be used.
• md writes a Markdown document to standard output, with a section per catalog entry, for reading by a person or by an agent.

tui is the default.

JSONL

$ terragrunt catalog --experiment=catalog-format --format=jsonl | head -1
{"kind":"module","title":"VPC","description":"Creates a VPC.","tags":["networking"],"source":"github.com/acme/infrastructure-modules","dir":"modules/vpc","version":"v0.14.2","url":"https://github.com/acme/infrastructure-modules/tree/main/modules/vpc","component_source":"github.com/acme/infrastructure-modules//modules/vpc","doc":"Everything a VPC needs.\n"}

Each entry is emitted as it is discovered, so a consumer that only needs the first few results can stop reading before discovery finishes.

Entries arrive in discovery order, which interleaves the repositories being loaded and differs between runs. Collect them before sorting when you need a stable order:

terragrunt catalog --experiment=catalog-format --format=jsonl | jq -s -c 'sort_by(.component_source)[]'

Every entry carries the body of the component’s README in doc, and no flag suppresses it. Drop it when you only want the metadata:

terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c 'del(.doc)'

Or keep only the fields you are after:

terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c '{kind, title, component_source}'

Entries follow a published JSON schema, which describes the schema for each entry, not the stream as a whole.

Markdown

terragrunt catalog --experiment=catalog-format --format=md > catalog.md

The document opens with a header describing what it holds, and gives each entry a section carrying the same metadata the jsonl format puts in a record:

## VPC

Creates a VPC.

| Field | Value |
| --- | --- |
| Kind | `module` |
| Source | `github.com/acme/infrastructure-modules` |
| Directory | `modules/vpc` |
| Version | `v0.14.2` |
| URL | <https://github.com/acme/infrastructure-modules/tree/main/modules/vpc> |
| Component source | `github.com/acme/infrastructure-modules//modules/vpc` |

| Tag |
| --- |
| `networking` |

A row is written only when the entry has a value for it, and an entry that declares no tags has no tag table. The component’s README follows, inside a fenced block, which keeps the headings a README carries from reading as sections of the catalog document.

Sections are written as entries are discovered, so a reader gets the first ones while the remaining repositories are still being cloned, and their order differs between runs. The document closes with a table naming every entry it holds and a count of what was discovered, which is what tells a complete document from one that was cut short.

See Non-interactive catalog for the whole shape of the document.

Type: string

Environment Variables:

• TG_FORMAT

--no-include-root

Do not include the root configuration file in any generated terragrunt.hcl file during scaffolding.

When enabled, Terragrunt will not automatically include the root configuration file in generated terragrunt.hcl files during scaffolding operations in the catalog.

This is useful when you want more control over which configurations are included in newly scaffolded modules.

Examples:

terragrunt catalog --no-include-root

Type: bool

Environment Variables:

• TG_NO_INCLUDE_ROOT

--root-file-name

The name of the root configuration file to include in any generated terragrunt.hcl during scaffolding.

Specifies the name of the root configuration file that should be:

• Included in generated terragrunt.hcl files during scaffolding
• Used when searching for Catalog URLs

This is particularly useful when your root configuration uses a different naming convention than the default.

Example:

terragrunt catalog --root-file-name root.hcl

Type: string

Environment Variables:

• TG_ROOT_FILE_NAME

--no-shell

Disable shell commands when using boilerplate templates in the catalog.

When enabled, Terragrunt will disable shell commands when processing boilerplate templates during catalog operations.

This is useful for security reasons when you want to prevent templates from executing arbitrary shell commands on your system.

Caution

Do not use catalog/scaffold to scaffold untrusted templates. IaC configurations are inherently powerful, as they can run arbitrary code on your system, so make sure to only use trusted templates you have reviewed and approved.

Note

Note that you will otherwise be prompted to confirm the execution of each shell command unless you are running in non-interactive mode.

Examples:

terragrunt catalog --no-shell

Type: bool

Environment Variables:

• TG_NO_SHELL

--no-hooks

Disable hooks when using boilerplate templates in the catalog.

When enabled, Terragrunt will disable hooks when processing boilerplate templates during catalog operations.

This is useful for security reasons when you want to prevent templates from executing arbitrary hooks on your system.

Caution

Do not use catalog/scaffold to scaffold untrusted templates. IaC configurations are inherently powerful, as they can run arbitrary code on your system, so make sure to only use trusted templates you have reviewed and approved.

Note

Note that you will otherwise be prompted to confirm the execution of each hook unless you are running in non-interactive mode.

Examples:

terragrunt catalog --no-hooks

Type: bool

Environment Variables:

• TG_NO_HOOKS

--no-cas

Disable the CAS (Content Addressable Storage) feature.

When this flag is set, Terragrunt skips all CAS operations and clones sources directly.

Generation or runs error when update_source_with_cas = true is set on any unit, stack, or terraform block reachable from the current invocation, since relative sources rewritten by CAS cannot be resolved without it.

Type: bool

Environment Variables:

• TG_NO_CAS

--cas-clone-depth

When using CAS, pass this value to git clone --depth (default 1; -1 clones full history).

This flag has no effect when the CAS is disabled with --no-cas.

Controls the --depth value the CAS (Content Addressable Storage) uses when cloning a Git source. The default of 1 performs a shallow clone of the latest commit. Negative values clone the full history by omitting --depth entirely; zero is rejected because Git requires a positive depth.

When passing a negative value, use the --cas-clone-depth=-1 form so the leading dash isn’t parsed as a flag.

This flag sets the depth for all CAS Git clones. A depth query parameter on a source URL (for example ...vpc.git?depth=1) is stripped before Terragrunt invokes git, and never changes the depth, which always comes from this flag.

Type: integer

Default: 1

Environment Variables:

• TG_CAS_CLONE_DEPTH

--cas-offline

When using CAS, never contact a remote; resolve every source from the local store and fail on anything missing.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-offline returns an error.

Forbids the CAS from contacting any remote. Each source is resolved locally instead: a source pinned to a specific revision that the store already holds is looked up there, and everything else is answered from the most recent probe the probe cache recorded for it, however old that result is. The content is then linked from the store as usual.

A source with no recorded answer, or whose content is not in the store, fails with an error naming it instead of being fetched. Run once without this flag to populate the store, then rerun with it.

Any other CAS failure on a source, such as a store file that cannot be read, also fails the run. Without this flag Terragrunt falls back to the standard downloader, which fetches from the remote.

terragrunt run --all --cas-offline -- plan

Every source the CAS resolves through a cheap probe is covered: Git, HTTP and HTTPS, S3, GCS, OCI, the OpenTofu/Terraform registry, and Mercurial. A source with no cheap probe, such as an SMB share, has nothing recorded and is still fetched. Local paths are copied as usual. The flag has no effect when the CAS is disabled with --no-cas, and it cannot be combined with --cas-refresh.

Type: bool

Environment Variables:

• TG_CAS_OFFLINE

--cas-refresh

When using CAS, ignore recorded probe results and ask every remote again.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-refresh returns an error.

Skips the probe cache for this run, so every source is resolved with a fresh probe. Units that resolve the same source at the same time still share one probe; a unit that starts later asks the remote again. The fresh results are recorded for later runs.

A source pinned to a specific revision, such as a semantic version tag or an S3 object version, is trusted for 24 hours by default, so a tag that has been moved keeps resolving to its previous revision until that window passes. This flag picks up the new one right away.

terragrunt run --all --cas-refresh -- plan

The flag has no effect when the CAS is disabled with --no-cas, and it cannot be combined with --cas-offline.

Type: bool

Environment Variables:

• TG_CAS_REFRESH

--cas-probe-ttl

When using CAS, trust a recorded probe of a source that can change upstream for this long before asking the remote again.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-probe-ttl returns an error.

Sets how long the CAS serves a recorded probe of a source that can change upstream in place of a fresh one. That covers a Git branch or HEAD, a Git tag that is not a semantic version, an HTTP endpoint, a GCS object, an OCI tag, and a Mercurial branch name. The value is a duration such as 30s, 10m, or 1h. Negative values are rejected.

The default of 0 probes these sources on every run, so a push or an upload followed by a run sees the new revision. Raise it when a burst of runs against the same sources should not each pay for a probe, accepting that a change made inside the window is not seen until it passes.

terragrunt run --all --cas-probe-ttl 10m -- plan

A source pinned to a specific revision is trusted for 24 hours regardless of this flag; see Recorded probes for which sources count as pinned. Use --cas-refresh to bypass every recorded result for one run.

Type: string

Default: 0

Environment Variables:

• TG_CAS_PROBE_TTL