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.

Experimental

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

Formats

• tui is the default format for the catalog command, and results in the catalog rendering 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.

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