Comprehensive guide for Terramate CLI, Cloud, and Catalyst, maintained by Terramate. Contains best practices and usage patterns for stack management, orchestration, code generation, Cloud integration, and Catalyst components/bundles.
When to Apply
Reference these guidelines when:
- Creating and organizing Terramate stacks
- Orchestrating commands across multiple stacks
- Using code generation to keep configurations DRY
- Integrating with Terramate Cloud for observability
- Creating Catalyst components and bundles
- Setting up CI/CD workflows with Terramate
- Managing stack dependencies and execution order
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | CLI Fundamentals | CRITICAL | cli- |
| 2 | CLI Orchestration | HIGH | cli-orchestration- |
| 3 | CLI Code Generation | HIGH | cli-codegen- |
| 4 | CLI Configuration | MEDIUM-HIGH | cli-config- |
| 5 | Terramate Cloud | MEDIUM-HIGH | cloud- |
| 6 | Terramate Catalyst | MEDIUM | catalyst- |
| 7 | CI/CD Integration | MEDIUM | cicd- |
| 8 | Advanced Patterns | LOW-MEDIUM | advanced- |
Quick Reference
1. CLI Fundamentals (CRITICAL)
cli-stack-structure- Organize stacks with clear directory structurecli-stack-config- Configure stacks with proper stack blockscli-stack-metadata- Use metadata for stack identification and filtering
2. CLI Orchestration (HIGH)
cli-orchestration-run- Run commands across stacks efficientlycli-orchestration-change-detection- Use change detection to limit execution scopecli-orchestration-parallel- Leverage parallel execution for independent stackscli-orchestration-dependencies- Manage stack dependencies and execution order
3. CLI Code Generation (HIGH)
cli-codegen-hcl- Use generate_hcl for DRY Terraform codecli-codegen-file- Use generate_file for file generation patternscli-codegen-provider- Generate provider configurations dynamically
4. CLI Configuration (MEDIUM-HIGH)
cli-config-globals- Use globals for shared configuration across stackscli-config-lets- Use lets for stack-local computed valuescli-config-metadata- Leverage metadata for stack information
5. Terramate Cloud (MEDIUM-HIGH)
cloud-integration- Set up Cloud connection and authenticationcloud-drift-management- Configure drift detection and reconciliationcloud-observability- Use Cloud dashboard for stack visibility
6. Terramate Catalyst (MEDIUM)
catalyst-components- Create reusable component blueprintscatalyst-bundles- Define bundles for component compositioncatalyst-instantiation- Instantiate bundles correctly
7. CI/CD Integration (MEDIUM)
cicd-github-actions- Set up GitHub Actions workflowscicd-preview-workflows- Create preview workflows for PRscicd-deployment-workflows- Configure deployment automation
8. Advanced Patterns (LOW-MEDIUM)
advanced-workflows- Create complex multi-step workflowsadvanced-codegen-patterns- Advanced code generation techniques
How to Use
Read individual rule files for detailed explanations and code examples:
rules/cli-stack-structure.md
rules/cli-orchestration-run.md
rules/cli-codegen-hcl.md
rules/cloud-integration.md
rules/catalyst-components.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect/anti-pattern example with explanation
- Correct/best practice example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md