Creating and Managing Templates¶

Templates are a core feature of ThothCTL that enable standardized project creation, component generation, and code reuse across your organization. This document outlines how to create, manage, and use templates with ThothCTL.

Overview¶

ThothCTL's template system allows you to:

1. Create standardized project structures for different types of infrastructure code
2. Enforce organizational best practices and coding standards
3. Accelerate development by providing pre-configured components
4. Maintain consistency across projects and teams
5. Define project parameters and validation rules through .thothcf.toml files

Template Types¶

ThothCTL supports several template types:

1. Project Templates: Complete project structures fetched from GitHub scaffold repositories
2. Component Templates: Reusable infrastructure components defined in .thothcf.toml
3. Stack Templates: Templates for creating infrastructure stacks via configuration

Template Placeholder Format¶

ThothCTL uses #{parameter_name}# expressions for parameterization in template files:

# Template
resource "aws_vpc" "main" {
  cidr_block = "#{vpc_cidr}#"
  tags = {
    Name        = "#{project}#-vpc"
    Environment = "#{environment}#"
  }
}

When instantiated, placeholders are replaced with the values provided by the user.

The .thothcf.toml File¶

The .thothcf.toml file is a critical component of every ThothCTL template. It defines:

1. Template input parameters and validation rules
2. Project structure requirements
3. Configuration for ThothCTL integration

For Terraform Projects¶

[thothcf]
project_id = "my-project"

[template_input_parameters.project_name]
template_value = "#{project}#"
condition = "^[a-zA-Z0-9_-]+$"
description = "Project Name"

[template_input_parameters.deployment_region]
template_value = "#{backend_region}#"
condition = "^[a-z]{2}-[a-z]{4,10}-\\d$"
description = "AWS Region"

[template_input_parameters.environment]
template_value = "#{environment}#"
condition = "(dev|qa|stg|test|prod)"
description = "Environment name (dev|qa|stg|test|prod)"

# Project structure definition
[project_structure]
root_files = [".git", ".gitignore", ".pre-commit-config.yaml", "README.md"]
ignore_folders = [".git", ".terraform", "Reports"]

For Terraform Modules¶

[template_input_parameters.module_name]
template_value = "#{ModuleName}#"
condition = "^[a-z_]+$"
description = "Module Name"

[template_input_parameters.description]
template_value = "#{ModuleDescription}#"
condition = "^[a-zA-Z\\s]+$"
description = "Module description"

[[project_structure.folders]]
name = "modules"
mandatory = true
content = ["variables.tf", "main.tf", "outputs.tf", "README.md"]
type = "root"

Creating Templates¶

From an Existing Project¶

The primary way to create a template is by converting a working project:

# Navigate to your project
cd my-terraform-project

# Convert to template
thothctl project convert --make-template --template-project-type terraform

# For Terragrunt projects
thothctl project convert --make-template --template-project-type terraform-terragrunt

This reads [project_properties] from .thothcf.toml, replaces values with #{placeholder}# expressions, and saves the template to ~/.thothcf/<project_name>/.

Setting Up Custom Template Repositories¶

Configure a custom GitHub repository as the scaffold source for a project type:

# Set a custom template URL
thothctl init template --project-type terraform --template-url https://github.com/myorg/custom-terraform.git

Using Templates¶

Creating Projects from Scaffold Templates¶

# Terraform + Terragrunt project (fetches from GitHub scaffold)
thothctl init project --project-name my-infra --project-type terraform-terragrunt

# CDK v2 project with language selection
thothctl init project --project-name my-app --project-type cdkv2 --language python

# Reuse template from VCS (Azure DevOps or GitHub space)
thothctl init project --project-name my-project --project-type terraform --reuse --space my-space

Creating Projects from Local Templates¶

# Create project from a previously saved local template
thothctl project convert --make-project --template-project-type terraform

Creating Components from Project Structure¶

# Create a component based on folder structure rules in .thothcf.toml
thothctl generate component \
  --component-type modules \
  --component-name networking \
  --component-path ./modules

Generating Stacks from Configuration¶

# Generate stacks from a YAML configuration file
thothctl generate stacks --config-file stack-config.yaml

# Create an example config to get started
thothctl generate stacks --create-example

Template Variables and .thothcf.toml Interaction¶

When you use a template, ThothCTL will:

1. Parse the .thothcf.toml file to identify required parameters
2. Prompt for values if not provided via command line
3. Validate input against the defined condition regex
4. Replace all occurrences of #{parameter_name}# in template files

Parameter Validation¶

The .thothcf.toml file includes regex conditions to validate input parameters:

[template_input_parameters.environment]
template_value = "#{environment}#"
condition = "(dev|qa|stg|test|prod)"
description = "Environment name (dev|qa|stg|test|prod)"

If a provided value doesn't match the condition, ThothCTL will show an error and prompt for a valid value.

Managing Templates¶

Storage Locations¶

Listing Available Templates¶

# Show available templates
thothctl list templates

# Show templates from a specific space
thothctl list templates --space my-space

Upgrading Projects from Templates¶

Keep projects in sync with template updates:

# Check what would change
thothctl project upgrade --dry-run

# Interactive file selection
thothctl project upgrade --interactive

# Force upgrade
thothctl project upgrade --force

Template Integration with Spaces¶

Templates can be associated with specific spaces via VCS providers (GitHub, Azure DevOps):

# Initialize a space
thothctl init space --space-name development

# Create project reusing a template from the space
thothctl init project --project-name my-project --project-type terraform --reuse --space development

Projects created within a space can discover templates from the space's VCS provider.

.thothcf.toml Reference¶

Template Input Parameters Section¶

[template_input_parameters.parameter_name]
template_value = "#{ParameterName}#"   # Placeholder in template files
condition = "regex_pattern"             # Validation regex
description = "Human-readable prompt"   # Shown during parameter input

Project Structure Section¶

[project_structure]
root_files = [".gitignore", "README.md"]
ignore_folders = [".git", ".terraform"]

[[project_structure.folders]]
name = "modules"
mandatory = true
type = "root"
content = ["main.tf", "variables.tf", "outputs.tf"]

Best Practices¶

1. Keep parameters meaningful — Use descriptive names and provide helpful descriptions
2. Validate strictly — Define specific regex patterns to catch errors early
3. Document templates — Include README and architecture docs in your templates
4. Version control — Store templates in Git repositories with semantic versioning
5. Test conversions — Always test make-project after creating a template
6. Define structure — Use [project_structure] to enforce required files and folders

Related Documentation¶

• Template Engine Overview
• GitHub Templates
• Project Convert
• Project Upgrade
• Platform Engineering Templates