CLI Reference¶

Learn the key commands and workflows for Cultivator.

Common Flags¶

These flags are available on plan, apply, and destroy:

Flag	Description	Default
`--config`	Path to config file	(none)
`--root`	Root directory for terragrunt modules	`.`
`--env`	Environment filter	(none)
`--include`	Relative paths to include (comma-separated or repeated)	(none)
`--exclude`	Relative paths to exclude (comma-separated or repeated)	(none)
`--tags`	Tag filters (comma-separated or repeated)	(none)
`--parallelism`	Max parallel executions	CPU count
`--non-interactive`	Add `-input=false` to Terragrunt commands	`false`
`--dry-run`	Print commands without executing them	`false`
`--graph`	Show Mermaid dependency graph	`false`
`--changed-only`	Only execute modules with changed files	`false`
`--base`	Git base reference for `--changed-only`	`HEAD`

Available Commands¶

Plan¶

Run terragrunt plan on matching stacks.

cultivator plan --root=live --env=dev --non-interactive

Command-specific options:

--destroy - run terragrunt plan -destroy

Apply¶

Run terragrunt apply on matching stacks.

cultivator apply --root=live --env=dev --non-interactive --auto-approve

Command-specific options:

--auto-approve - add -auto-approve

Destroy¶

Run terragrunt destroy on matching stacks.

cultivator destroy --root=live --env=dev --non-interactive --auto-approve

Command-specific options:

--auto-approve - add -auto-approve

Doctor¶

Verify your environment and configuration. Checks for Terragrunt in PATH, validates the config file (if provided), and confirms the root directory exists.

cultivator doctor --root=live
cultivator doctor --root=live --config=cultivator.yml

Flags: --config, --root

Version¶

Print version information.

cultivator version

Example output:

cultivator v0.3.10 (commit abc1234, built 2026-01-15T12:00:00Z)

CLI Examples¶

Plan specific environment¶

./cultivator plan --root=live --env=prod --non-interactive

Plan specific stacks¶

./cultivator plan --root=live --include=envs/prod/app1,envs/prod/app2 --non-interactive

Plan excluding experimental stacks¶

./cultivator plan --root=live --exclude=experimental --non-interactive

Plan only stacks with specific tags¶

./cultivator plan --root=live --tags=critical --non-interactive

Plan with custom parallelism¶

./cultivator plan --root=live --parallelism=8 --non-interactive

Magic Mode: Plan only changed modules¶

Compare current branch against main and only run plan on modules that have file changes.

./cultivator plan --changed-only --base=main

CLI Arguments & Flags¶

Positional Arguments¶

Cultivator supports a positional argument for the module path. This is a shorthand for filtering to a specific module.

cultivator plan cloudwatch/log-group/example

Note: The path is automatically normalized (e.g., removing leading ./ or trailing /terragrunt.hcl).

Environment Variables¶

Variable	Values	Default	Description
`CULTIVATOR_LOG_LEVEL`	`debug`, `info`, `warning`, `error`	`info`	Minimum log level.
`CULTIVATOR_ROOT`	path	`.`	Root directory for discovery.
`CULTIVATOR_ENV`	string		Environment filter.
`CULTIVATOR_INCLUDE`	comma-separated paths		Paths to include.
`CULTIVATOR_EXCLUDE`	comma-separated paths		Paths to exclude.
`CULTIVATOR_TAGS`	comma-separated tags		Tag filters.
`CULTIVATOR_PARALLELISM`	integer	CPU count	Max parallel executions.
`CULTIVATOR_NON_INTERACTIVE`	`true`, `false`	`false`	Force non-interactive mode.
`CULTIVATOR_DRY_RUN`	`true`, `false`	`false`	Enable dry-run mode.
`CULTIVATOR_SHOW_GRAPH`	`true`, `false`	`false`	Enable Mermaid graph output.
`CULTIVATOR_CHANGED_ONLY`	`true`, `false`	`false`	Enable Magic Mode (Git changes).
`CULTIVATOR_BASE_REF`	string	`HEAD`	Git base reference for Magic Mode.

Example — enable Magic Mode in CI:

CULTIVATOR_CHANGED_ONLY=true CULTIVATOR_BASE_REF=main cultivator plan

Debugging and Verbose Logging¶

If you are experiencing issues with module discovery or filtering, you can enable verbose logging by setting the CULTIVATOR_LOG_LEVEL environment variable to debug.

CULTIVATOR_LOG_LEVEL=debug cultivator plan --root=live

Verbose mode provides detailed information about:

Starting the discovery process with normalized paths.
Directories being skipped (e.g., .git, node_modules).
Filter matching logic (include/exclude/environment/tags).
Dependency extraction for each module.

This is especially useful for troubleshooting why a specific module was or was not included in the execution set.

Output Format¶

Cultivator produces human-readable text output by default, organized by module with clear section headers:

=== plan: live/prod/vpc ===
Running terragrunt plan in /path/to/live/prod/vpc...
[output from terragrunt]

=== plan: live/prod/app ===
Running terragrunt plan in /path/to/live/prod/app...
[output from terragrunt]

Each stack shows:

Module path
Terragrunt output and any errors
Clear demarcation for easy scanning

Implementation note: Cultivator automatically appends -no-color to every Terragrunt invocation to produce clean, parseable output in CI environments.

Binary Invocation¶

Local development (after building):

go build -o cultivator ./cmd/cultivator
./cultivator plan --root=live --env=dev

CI/CD environments (pre-compiled/downloaded binaries in PATH):

cultivator plan --root=live --env=dev

Both forms are equivalent. The difference:

./cultivator - Runs binary in current directory (local builds)
cultivator - Runs binary found in system PATH (CI/production installs)

Exit Codes¶

0 - Success (all stacks executed successfully)
1 - Failure (one or more stacks failed)
2 - Usage error (invalid flags or arguments)

Execution Metrics¶

Cultivator automatically tracks and reports execution time:

Per-module duration: Displayed in the logs for each module upon completion.
Total duration: Displayed at the end of the command execution.

These metrics help identify infrastructure bottlenecks and optimize CI/CD runtime.

Summary Table¶

At the end of each execution, Cultivator displays a summary table with the following information:

Module: The relative path to the module.
Command: The Terragrunt command executed.
Status: SUCCESS or FAILURE.
Duration: The time taken to execute the module.
Notes: Additional context, such as exit codes or error messages.

This table provides a high-level overview of the entire run, making it easy to identify failed modules in large projects.

Standard Workflow¶

For pull requests + main branch merges:

PR triggers plan:

cultivator plan --root=live --env=dev --non-interactive

Review plan output
Merge PR
Main branch triggers apply:

cultivator apply --root=live --env=dev --non-interactive --auto-approve

See Features for more about what Cultivator can do.