Appearance

List ​

The terramate list command lists all Terramate stacks in the current directory recursively. These can be additionally filtered based on Terramate Cloud status with the --status=<status> filter (valid statuses are documented on the trigger page)

Usage ​

terramate list [options]

Examples ​

List all stacks in the current directory recursively: ​

bash
terramate list

List all stacks in the current directory sorted by order of execution: ​

bash
terramate list --run-order

Explicitly change the working directory: ​

bash
terramate list --chdir path/to/directory

List all stacks below the current directory that have a "drifted" status on Terramate Cloud ​

bash
terramate list --status=drifted

List all changed stacks ignoring untracked files ​

terramate list --changed --disable-change-detection=git-untracked

List changed stacks and their dependencies ​

bash
terramate list --changed --include-all-dependencies

List only stacks that depend on changed stacks ​

bash
terramate list --changed --only-all-dependents

Options ​

  • -C, --chdir=<path>: Set the working directory.
  • -B, --git-change-base=<ref>: Specify the Git base ref for computing changes.
  • -c, --changed: Filter stacks by changed infrastructure.
  • --enable-change-detection=<options>: Enable specific change detection features. Supported values include: 'git-untracked' and 'git-uncommitted' (multiple options allowed).
  • --disable-change-detection=<options>: Disable specific change detection features. Supported values include: 'git-untracked' and 'git-uncommitted' (multiple options allowed).
  • --tags=<tags>: Filter stacks by tags. Use ":" for logical AND and "," for logical OR. Examples:
    • --tags=app:prod filters stacks containing tag "app" AND "prod".
    • If multiple --tags options are provided, an OR expression is created. Example: --tags=a --tags=b is the same as --tags=a,b.
  • --no-tags=<no-tags>: Filter stacks that do not have the given tags.
  • --log-level=<level>: Set the log level. Possible values include 'disabled', 'trace', 'debug', 'info', 'warn', 'error', or 'fatal'.
  • --log-fmt=<format>: Choose the log format. Options are 'console', 'text', or 'json'.
  • --log-destination=<destination>: Set the destination of log messages. Default is stderr.
  • --quiet: Disable output.
  • -v, --verbose=<level>: Increase the verbosity of the output. The level is optional and defaults to 0 if not specified.
  • --why: Show the reason why a stack has changed.
  • --status=<status>: Filter by status on Terramate Cloud.
    • If the experimental deployment targets option is enabled, --target is required (see run).
  • --run-order: Sort stacks by order of execution.

Dependency Filters ​

These flags allow you to expand or narrow the selection of stacks by including or excluding their dependencies and dependents. They work with both Terramate dependencies (via input.from_stack_id) and Terragrunt dependencies (via dependency blocks). See the Change Detection dependency filters documentation for details.

WARNING

Dependency filters only consider data dependencies (stacks that share outputs or data), not ordering or forced-execution relationships. Stacks defined in stack.wants, stack.wanted_by, stack.before, or stack.after are not considered dependencies for filtering purposes. See the Change Detection documentation for details.

Include Dependencies ​

  • --include-all-dependencies: Add all stacks that the selected stacks depend on (direct + transitive) to the selection
  • --include-direct-dependencies: Add stacks that the selected stacks directly depend on to the selection

Replace with Dependencies ​

  • --only-all-dependencies: Replace selection with only all stacks that the selected stacks depend on (direct + transitive)
  • --only-direct-dependencies: Replace selection with only stacks that the selected stacks directly depend on

Exclude Dependencies ​

  • --exclude-all-dependencies: Remove all stacks that the selected stacks depend on from the selection

Include Dependents ​

  • --include-all-dependents: Add all stacks that depend on the selected stacks (direct + transitive) to the selection
  • --include-direct-dependents: Add stacks that directly depend on the selected stacks to the selection

Replace with Dependents ​

  • --only-all-dependents: Replace selection with only all stacks that depend on the selected stacks (direct + transitive)
  • --only-direct-dependents: Replace selection with only stacks that directly depend on the selected stacks

Exclude Dependents ​

  • --exclude-all-dependents: Remove all dependent stacks from the selection

INFO

Only one of --only-all-dependencies, --only-direct-dependencies, --only-direct-dependents, or --only-all-dependents can be used at a time, as they replace the selection.