Use this command to Initialize a project, environment, or space.
thothctl init --help
Usage: thothctl init [OPTIONS] COMMAND [ARGS]...
Initialize and setup project configurations
Options:
--help Show this message and exit.
Commands:
env Initialize a development environment with required tools and...
project Initialize a new project
space Initialize a new space
The thothctl init project command initializes a new project with the ThothCTL framework. This command creates the necessary project structure, configuration files, and optionally sets up version control integration. Projects can be associated with spaces for consistent configuration and credential management.
Usage: thothctl init project [OPTIONS]
Initialize a new project
Options:
-p, --project-name TEXT Name of the project [required]
-pt, --project-type [terraform|tofu|cdkv2|terraform_module|terragrunt|custom]
Type of project to create [default: terraform]
-sc, --setup-conf Setup project configuration [default: True]
-vcss, --version-control-systems-service [azure_repos|github|gitlab]
The Version Control System Service for you IDP
[default: azure_repos]
-reuse, --reuse Reuse templates, pattern, PoC, projects and
more from your IDP catalog
-az-org, --az-org-name TEXT Azure organization name (for Azure Repos)
-gh-user, --github-username TEXT
GitHub username or organization (for GitHub)
-s, --space TEXT Space name for the project (used for loading
credentials and configurations)
--batch Run in batch mode with minimal prompts and use
default values where possible
--help Show this message and exit.
thothctl init project --project-name my-terraform-project
This creates a new Terraform project with the default structure.
thothctl init project --project-name my-project --setup_conf
This creates a new project and sets up the .thothcf.toml configuration file.
thothctl init project --project-name my-project --space development
This creates a new project in the “development” space, inheriting the space’s configurations.
thothctl init project --project-name my-cdk-project --project-type cdkv2
This creates a new project using the CDKv2 template.
thothctl init project --project-name my-terragrunt-project --project-type terragrunt --space development
This creates a new Terragrunt project in the “development” space with the appropriate structure for Terragrunt orchestration.
ThothCTL supports the following project types:
Each project type has a predefined structure and set of files that will be created.
When you initialize a project, ThothCTL creates the following structure:
my-project/
├── .gitignore
├── .pre-commit-config.yaml
├── .thothcf.toml
├── .tflint.hcl
├── common/
│ ├── common.hcl
│ └── common.tfvars
├── README.md
└── root.hcl
When you run thothctl init project --project-type terragrunt, the following scaffold structure is created:
my-terragrunt-project/
├── .gitignore # Git ignore rules for Terraform/Terragrunt artifacts
├── .pre-commit-config.yaml # Pre-commit hooks (terraform fmt, tflint, docs)
├── .thothcf.toml # ThothCTL project configuration and metadata
├── .tflint.hcl # TFLint configuration for static analysis
├── README.md # Project documentation
├── root.hcl # Terragrunt root configuration (remote state, common inputs)
├── common/ # Shared configuration across all stacks
│ ├── common.hcl # Common Terragrunt locals (project name, region, backend settings)
│ ├── common.tfvars # Shared Terraform variable values
│ └── variables.tf # Shared variable declarations
├── docs/ # Project documentation and diagrams
│ ├── DiagramArchitecture.png # Architecture diagram
│ └── graph.svg # Dependency graph visualization
├── modules/ # Reusable Terraform modules for this project
│ ├── main.tf # Module resource definitions
│ ├── outputs.tf # Module output declarations
│ ├── README.md # Module documentation
│ └── variables.tf # Module input variable declarations
└── stacks/ # Terragrunt stack definitions (deployment units)
├── README.md # Stacks overview and usage guide
├── terragrunt.hcl # Stacks-level Terragrunt config (includes root.hcl)
├── graph.svg # Stacks dependency graph
└── compute/ # Category grouping (e.g., compute, network, storage)
└── EC2/ # Service grouping
└── ALB_Main/ # Individual stack (deployment unit)
├── README.md # Stack-specific documentation
├── terragrunt.hcl # Stack Terragrunt config (source, dependencies, inputs)
└── graph.svg # Stack resource graph
| Directory/File | Purpose |
|---|---|
| Root files | Project-wide configuration and tooling setup |
root.hcl |
Terragrunt root configuration — defines remote state (S3 backend), init arguments, and imports common variables |
common/ |
Shared configuration consumed by all stacks via read_terragrunt_config() |
common/common.hcl |
Terragrunt locals: project name, backend bucket, region, profile, DynamoDB lock table |
common/common.tfvars |
Terraform variable values shared across all stacks |
docs/ |
Architecture diagrams and project-level documentation assets |
modules/ |
Project-scoped reusable Terraform modules (not published externally) |
stacks/ |
Deployment units organized by category → service → stack name |
stacks/terragrunt.hcl |
Includes root.hcl and exposes it to child stacks |
Stacks follow a hierarchical naming convention:
stacks/<category>/<service>/<stack_name>/
compute, network, storage, database, security)EC2, VPC, RDS, S3)ALB_Main, Primary, Replica)Each stack’s terragrunt.hcl includes the root configuration and defines its Terraform source:
include "root" {
path = find_in_parent_folders("root.hcl")
expose = true
}
The scaffold is loaded from the thothforge/terragrunt_project_scaffold GitHub repository. If the repository is unreachable, ThothCTL falls back to the built-in local template.
The main configuration file for ThothCTL projects:
[template_input_parameters.project_name]
template_value = "my-project"
condition = "\b[a-zA-Z]+\b"
description = "Project Name"
[template_input_parameters.deployment_region]
template_value = "us-east-1"
condition = "^[a-z]{2}-[a-z]{4,10}-\d$"
description = "AWS Region"
# Additional configuration parameters...
[thothcf]
version = "1.0.0"
space = "development" # If project is in a space
When you create a project within a space using the --space option, the project inherits:
This ensures consistency across all projects within the same space.
ThothCTL supports integration with Azure DevOps for template reuse and repository setup.
thothctl init project --project-name my-project --reuse --az-org-name my-organization -r -list
This lists all available templates in your Azure DevOps organization.
thothctl init project --project-name my-project --reuse --az-org-name my-organization
This prompts you to select a template from your Azure DevOps organization and creates a project based on that template.
When setting up a project configuration, ThothCTL collects and stores the following properties:
These properties are used for template substitution and configuration generation.
ThothCTL supports template substitution in project files. For example, test-wrapper in templates will be replaced with the actual project name.
thothctl init project --project-name terraform-vpc --project-type terraform --setup-conf
thothctl init project --project-name vpc-module --project-type terraform_module --space shared-modules
thothctl init project --project-name terragrunt-infra --project-type terragrunt --space production --batch
thothctl init project --project-name cdk-app --project-type cdkv2 --reuse --github-username my-organization
--setup_conf flag to set up the project configuration💥 Project "my-project" already exists.
Run 👉 thothctl remove -pj my-project 👈🏼 if you want to reuse the project name.
Solution: Either choose a different project name or remove the existing project.
Error: Invalid value for "--project-type": "invalid-type" is not one of "terraform", "tofu", "cdkv2", "terraform_module", "terragrunt", "custom".
Solution: Use one of the supported project types.
Error: Space "non-existent-space" not found
Solution: Create the space first or use an existing space.
For more detailed logs, run ThothCTL with the --debug flag:
thothctl --debug init project --project-name my-project