ThothCTLβs AI-DLC lets you interact with your infrastructure lifecycle using AI assistants. Instead of memorizing CLI flags, you describe what you need β the AI executes the right commands and explains the results.
| Use Case | What Youβll Achieve | Time |
|---|---|---|
| Generate infrastructure from intent | Working Terraform/Terragrunt from a description | 2 min |
| Security review with AI agents | Findings + auto-generated fixes + PR decision | 3 min |
| Full DevSecOps pipeline via AI | Cost + security + blast radius in one conversation | 5 min |
| Analyze planned changes | Cost estimate + risk assessment from plan files | 3 min |
| Detect and fix drift | Drifted resources + remediation guidance | 2 min |
| Generate documentation | README, dependency graphs, architecture diagrams | 1 min |
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#3f51b5','primaryTextColor':'#fff','primaryBorderColor':'#303f9f','lineColor':'#536dfe','secondaryColor':'#536dfe','tertiaryColor':'#fff'}}}%%
graph TB
A["π€ AI Assistant<br/>Kiro Β· Claude Β· Copilot"] --> B{"Workflow Choice"}
B -->|"Option 1:<br/>AI Orchestrates"| C["π‘ MCP Server<br/>AI calls ThothCTL tools"]
B -->|"Option 2:<br/>Manual + AI Analysis"| D["π» Direct CLI<br/>Developer runs commands"]
C --> E["βοΈ ThothCTL Engine<br/>generate, scan, check,<br/>ai-review, inventory, workflow"]
D --> E
E --> F["π Results & Reports<br/>JSON, HTML, Findings, SBOM"]
F --> G["π§ AI Analysis<br/>Insights, Summaries,<br/>Fixes, Decisions"]
G --> H["π Action<br/>Deploy, Fix, Document,<br/>Create PR"]
H --> A
classDef aiStyle fill:#3f51b5,stroke:#5c6bc0,stroke-width:3px,color:#fff
classDef choiceStyle fill:#f57f17,stroke:#fbc02d,stroke-width:3px,color:#fff
classDef mcpStyle fill:#0277bd,stroke:#039be5,stroke-width:3px,color:#fff
classDef cliStyle fill:#2e7d32,stroke:#43a047,stroke-width:3px,color:#fff
classDef engineStyle fill:#ef6c00,stroke:#fb8c00,stroke-width:3px,color:#fff
classDef resultsStyle fill:#c2185b,stroke:#e91e63,stroke-width:3px,color:#fff
classDef analysisStyle fill:#7b1fa2,stroke:#9c27b0,stroke-width:3px,color:#fff
classDef actionStyle fill:#00695c,stroke:#00897b,stroke-width:3px,color:#fff
class A aiStyle
class B choiceStyle
class C mcpStyle
class D cliStyle
class E engineStyle
class F resultsStyle
class G analysisStyle
class H actionStyle
Two ways to use it:
kiro-cli chat --agent thoth, describe what you need in natural language, the agent executes ThothCTL commands via MCP and explains results.thothctl commands yourself, then start kiro-cli chat --agent thoth to analyze results, prioritize findings, and get fix suggestions.# Install with pip
pip install thothctl
# Or install with pipx (recommended β isolated environment, no conflicts)
pipx install thothctl
# Already installed? Upgrade to latest version
thothctl upgrade
# Or with pip/pipx
pip install --upgrade thothctl
pipx upgrade thothctl
Add ThothCTL to your AI assistantβs MCP configuration:
=== βKiro CLI (~/.kiro/settings/mcp.json)β
```json
{
"mcpServers": {
"thothctl": {
"command": "thothctl",
"args": ["mcp", "server", "--stdio"]
}
}
}
```
=== βClaude Code (~/.claude/settings/mcp.json)β
```json
{
"mcpServers": {
"thothctl": {
"command": "thothctl",
"args": ["mcp", "server", "--stdio"]
}
}
}
```
=== βPer-project (.kiro/settings/mcp.json)β
```json
{
"mcpServers": {
"thothctl": {
"command": "thothctl",
"args": ["mcp", "server", "--stdio"]
}
}
}
```
# For local AI review without cloud costs
# Install Ollama: https://ollama.ai
ollama pull llama3.1:8b
thothctl --version # Should show v0.27+
thothctl mcp status # Should show server available
ollama list # (optional) Shows local models
Goal: Describe what you need β get working, compliant IaC code.
# Initialize a project first (sets up scaffold + org rules)
thothctl init project -p my-infrastructure --project-type terraform-terragrunt --space production
# Start Kiro CLI with the ThothCTL agent
cd my-infrastructure
kiro-cli chat --agent thoth
=== βVia Kiro CLI (AI Agent)β
Once inside the `kiro-cli chat --agent thoth` session:
```
You: "Generate a VPC with 3 private subnets, NAT gateway, and flow logs
for production in us-east-1"
```
The agent uses ThothCTL MCP tools to generate, validate, and self-correct automatically.
=== βVia CLI (no AI assistant)β
```bash
thothctl generate iac \
--intent "VPC with 3 private subnets, NAT gateway, and flow logs" \
--project-type terraform-terragrunt \
--provider ollama \
--space production \
--apply
```
π Generating infrastructure code...
βββ Loading org rules from .thothcf.toml
βββ Using scaffold: terraform-terragrunt
βββ AI generating HCL code...
βββ Validating with Checkov...
β βββ β 1 violation: VPC flow logs not enabled
βββ Self-correcting (iteration 2/5)...
βββ Re-validating...
β βββ β
0 violations
βββ Running terraform plan...
βββ β
Plan succeeded (7 resources to create)
β
Generated files:
stacks/foundation/network/vpc/
βββ main.tf (VPC + subnets + NAT + flow logs)
βββ variables.tf (region, cidr, environment)
βββ outputs.tf (vpc_id, subnet_ids, nat_gateway_ip)
βββ terragrunt.hcl (backend + provider config)
π Estimated cost: $142/month
π Architecture diagram: docs/vpc-architecture.mmd
cd stacks/foundation/network/vpc
terragrunt plan # Verify the generated code
terragrunt apply # Deploy when satisfied
| Type | Flag | What Gets Generated |
|---|---|---|
| Terraform | --project-type terraform |
main.tf, variables.tf, outputs.tf |
| Terragrunt | --project-type terraform-terragrunt |
Multi-stack with terragrunt.hcl per stack |
| CloudFormation | --project-type cloudformation |
template.yaml with Parameters/Resources/Outputs |
| CDK v2 | --project-type cdkv2 |
TypeScript/Python CDK constructs |
# Requires an AI provider. Choose one:
# Option A: Local Ollama (free, private β install from https://ollama.ai)
ollama pull llama3.1:8b
thothctl generate iac \
--intent "S3 bucket with encryption and versioning" \
--project-type terraform \
--provider ollama
# Option B: AWS Bedrock (requires AWS credentials with Bedrock access)
thothctl generate iac \
--intent "S3 bucket with encryption and versioning" \
--project-type terraform \
--provider bedrock
# Option C: OpenAI (requires OPENAI_API_KEY env var)
thothctl generate iac \
--intent "S3 bucket with encryption and versioning" \
--project-type terraform \
--provider openai
# Add --apply to write files to disk (dry-run by default)
!!! note βProvider Requiredβ
generate iac requires an AI provider to produce code. Without --provider,
ThothCTL will use the provider configured in .thothcf.toml or prompt you to set one up.
Goal: Get AI agents to analyze your IaC, find security issues, suggest fixes, and decide if a PR is safe.
=== βVia Kiro CLI (AI Agent)β
```bash
# Start Kiro CLI with the ThothCTL agent
kiro-cli chat --agent thoth
```
Then in the chat session:
```
You: "Review my Terraform code in ./stacks for security issues"
```
=== βVia CLI (direct)β
```bash
# With local Ollama (free, private)
thothctl ai-review analyze -d ./stacks -p ollama
# With AWS Bedrock (Claude)
thothctl ai-review analyze -d ./stacks -p bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
# With OpenAI
thothctl ai-review analyze -d ./stacks -p openai
```
π Security Agent:
- IAM role has wildcard s3:* permissions (iam.tf:15) β HIGH
- S3 bucket allows public access (storage.tf:8) β HIGH
- RDS not encrypted at rest (database.tf:22) β MEDIUM
ποΈ Architecture Agent:
- EKS on single AZ (cluster.tf:5) β Consider multi-AZ for HA
- No autoscaling on node group β Add cluster-autoscaler
π§ Fix Agent:
- Generated fix for iam.tf: Replace "s3:*" with ["s3:GetObject", "s3:PutObject"]
- Generated fix for storage.tf: Add aws_s3_bucket_public_access_block
- Generated fix for database.tf: Add storage_encrypted = true
βοΈ Decision Agent:
Verdict: REQUEST_CHANGES (confidence: 0.91)
Reason: 2 HIGH security findings must be resolved before merge
# Dry-run β shows what decision would be posted
thothctl ai-review decide -d ./stacks --pr-number 42 --dry-run
# Post decision to PR (GitHub/GitLab/Azure DevOps)
thothctl ai-review decide -d ./stacks --pr-number 42
| Provider | Flag | Cost | Best For |
|---|---|---|---|
| Ollama | -p ollama |
Free | Local dev, privacy, testing |
| AWS Bedrock | -p bedrock |
Pay-per-token | Enterprise, Claude models |
| OpenAI | -p openai |
Pay-per-token | GPT-4o, broad availability |
| Azure OpenAI | -p azure |
Pay-per-token | Azure compliance requirements |
# Quickest test β uses local Ollama
ollama pull llama3.1:8b
thothctl ai-review analyze -d . -p ollama
Goal: Execute the full DevSecOps lifecycle (cost β structure β inventory β security β blast radius β drift) in one conversation or one command.
# Start Kiro CLI with the ThothCTL agent
kiro-cli chat --agent thoth
Then in the chat session:
You: "Run the full DevSecOps pipeline on my infrastructure"
AI: [Executes thothctl workflow devsecops --phase all]
π Results:
βββββββββββββ¬βββββββββββ¬ββββββββββββββββββββββββββββββββ
β Phase β Status β Summary β
βββββββββββββΌβββββββββββΌββββββββββββββββββββββββββββββββ€
β Plan β β
Pass β Cost: $2,847/mo β
β Develop β β
Pass β Structure valid β
β Build β β
Pass β 12 modules, 3 outdated β
β Test β β
Pass β 0 plan errors β
β Secure β β οΈ Warn β 3 HIGH, 5 MEDIUM findings β
β Deploy β β
Pass β Blast radius: Medium β
β Monitor β β
Pass β 0 drifted resources β
βββββββββββββ΄βββββββββββ΄ββββββββββββββββββββββββββββββββ
β οΈ 3 HIGH severity findings in Secure phase.
Would you like me to show details and fixes?
# Full pipeline (soft enforcement β report only)
thothctl workflow devsecops --phase all
# Pre-deploy gate (hard enforcement β fails on violations)
thothctl workflow devsecops --phase pre-deploy --enforcement hard
# Single phase
thothctl workflow devsecops --phase secure
# Run a custom workflow DAG
thothctl workflow run --file .thothcf_workflow.yaml
# Dry-run to see execution plan
thothctl workflow run --file .thothcf_workflow.yaml --dry-run
| Phase | What It Does | CLI Flag |
|---|---|---|
| Plan | Cost analysis + blast radius | --phase plan |
| Develop | Environment check + project structure | --phase develop |
| Build | Inventory + version checks (SBOM) | --phase build |
| Test | Terraform plan validation | --phase test |
| Secure | Multi-tool scanning (Checkov, Trivy, OPA) | --phase secure |
| Deploy | Security gate (hard enforcement) | --phase deploy |
| Monitor | Drift detection | --phase monitor |
| Pre-deploy | Test + Secure combined (CI/CD gate) | --phase pre-deploy |
| All | Full pipeline | --phase all |
# Quickest test β just the security phase
thothctl workflow devsecops --phase secure
# Full pipeline
thothctl workflow devsecops --phase all
π For detailed phase descriptions, plan generation per framework, and CI/CD integration, see the DevSecOps SDLC Guide.
Goal: Before deploying, understand what it will cost and what could break.
Plans are framework-specific. Generate one using your IaC tool:
=== βTerragrunt (multi-stack)β
```bash
terragrunt run \
--working-dir stacks/ \
--all \
--out-dir tfplan \
--json-out-dir tfplan \
-- plan -lock=false
```
Output: `tfplan/` directory with JSON plans per stack.
=== βTerraform / OpenTofuβ
```bash
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
```
Output: single `tfplan.json` file.
=== βCloudFormationβ
```bash
# Create change set
aws cloudformation create-change-set \
--stack-name my-stack \
--template-body file://template.yaml \
--change-set-name analyze-changes
```
Or analyze directly from template: `--template template.yaml`
=== βCDK v2β
```bash
cdk synth --output cdk.out
```
Analyze the synthesized template: `--template cdk.out/MyStack.template.json`
=== βVia Kiro CLI (AI Agent)β
```bash
kiro-cli chat --agent thoth
```
Then in the chat session:
```
You: "Analyze the cost and blast radius for my planned changes"
AI: [Calls cost_analysis + check_iac with blast-radius]
π° Cost Impact: +$340/month across 5 stacks
- EKS node scaling: +$280/mo
- New RDS read replica: +$60/mo
π Blast Radius: HIGH
- 14 resources affected
- 3 cross-stack dependencies
- EKS node group: rolling update (potential 5min downtime)
Recommendation: Deploy foundation layer first, wait 10 min,
then deploy platform layer.
```
=== βVia CLIβ
```bash
# Cost analysis
thothctl check iac -type cost-analysis --plan-file tfplan/ --recursive
# Blast radius
thothctl check iac -type blast-radius --plan-file tfplan/ --recursive
```
# Generate a plan and analyze it
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
thothctl check iac -type cost-analysis --plan-file tfplan.json
thothctl check iac -type blast-radius --plan-file tfplan.json
Goal: Find resources that have drifted from your IaC definition and get remediation guidance.
=== βVia Kiro CLI (AI Agent)β
```bash
kiro-cli chat --agent thoth
```
Then in the chat session:
```
You: "Check for drift in my production infrastructure"
```
=== βVia CLI (direct)β
```bash
# Basic drift detection
thothctl check iac -type drift --recursive
# With AI-powered root cause analysis
thothctl check iac -type drift --recursive --ai-provider ollama
```
π Drift Detection Results:
ββββββββββββββββββββββββββββββ¬βββββββββββ¬ββββββββββββββββββββββββββ
β Resource β Severity β What Changed β
ββββββββββββββββββββββββββββββΌβββββββββββΌββββββββββββββββββββββββββ€
β aws_security_group.web β HIGH β Ingress rule added β
β aws_s3_bucket.logs β MEDIUM β Lifecycle rule removed β
β aws_iam_role.lambda β LOW β Tag modified β
ββββββββββββββββββββββββββββββ΄βββββββββββ΄ββββββββββββββββββββββββββ
π΄ HIGH: aws_security_group.web
Someone manually added an ingress rule allowing 0.0.0.0/0 on port 22.
Your IaC restricts SSH to VPN CIDR (10.0.0.0/8) only.
Remediation: Run `terraform apply` to reconcile back to desired state.
This will REMOVE the dangerous rule.
# Preview what terraform would change
terraform plan
# Apply to reconcile (removes manual drift)
terraform apply
# Requires cloud credentials (reads actual state)
thothctl check iac -type drift --recursive
Goal: Auto-generate README, dependency graphs, and architecture diagrams from your IaC code.
=== βVia Kiro CLI (AI Agent)β
```bash
kiro-cli chat --agent thoth
```
Then in the chat session:
```
You: "Generate documentation for my infrastructure project"
```
=== βVia CLI (direct)β
```bash
# Generate docs for all stacks
thothctl document iac --recursive
# Terragrunt dependency graph
thothctl document iac --framework terragrunt --graph-type mermaid
```
β
Generated documentation:
βββ stacks/foundation/network/vpc/README.md
βββ stacks/foundation/iam/roles/README.md
βββ stacks/platform/eks/cluster/README.md
βββ docs/dependency-graph.mmd (Mermaid)
βββ docs/topology.png (architecture diagram)
thothctl document iac --recursive
The complete AI-DLC flow connects generation, validation, review, and monitoring:
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#e3f2fd','primaryTextColor':'#1565c0','primaryBorderColor':'#1976d2','lineColor':'#42a5f5','secondaryColor':'#fff3e0','tertiaryColor':'#f3e5f5','fontSize':'14px'}}}%%
graph TD
intent["<b>1. Developer Intent</b><br/><small>'I need a VPC with...'</small>"]:::startNode
gen["<b>2. Generate IaC</b><br/><small>generate iac β validated code</small>"]:::genNode
plan["<b>3. Plan & Analyze</b><br/><small>terraform plan β cost + blast radius</small>"]:::planNode
scan["<b>4. Scan & Review</b><br/><small>scan iac + ai-review β findings</small>"]:::scanNode
deploy["<b>5. Deploy</b><br/><small>terraform apply</small>"]:::deployNode
monitor["<b>6. Monitor</b><br/><small>drift detection + dashboard</small>"]:::monitorNode
intent --> gen
gen --> plan
plan --> scan
scan -->|"β
Approved"| deploy
scan -->|"β Changes needed"| gen
deploy --> monitor
monitor -->|"Drift detected"| scan
classDef startNode fill:#7c4dff,stroke:#6200ea,stroke-width:2px,color:#fff
classDef genNode fill:#2196f3,stroke:#1565c0,stroke-width:2px,color:#fff
classDef planNode fill:#ff9800,stroke:#e65100,stroke-width:2px,color:#fff
classDef scanNode fill:#e91e63,stroke:#880e4f,stroke-width:2px,color:#fff
classDef deployNode fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
classDef monitorNode fill:#00bcd4,stroke:#006064,stroke-width:2px,color:#fff
Each step can be run:
thothctl workflow devsecops --phase allThothCTL exposes 26 tools via the Model Context Protocol. Your AI assistant can call any of these:
| Category | Tool | What It Does |
|---|---|---|
| Generation | thothctl_generate_iac |
Natural language β governed IaC code |
| Β | thothctl_generate_stacks |
YAML-driven stack generation |
| Security | thothctl_scan_iac |
Multi-tool scanning (Checkov, Trivy, KICS, OPA) |
| Β | thothctl_ai_review |
Multi-agent AI security analysis + PR decisions |
| Analysis | thothctl_check_iac |
Cost analysis, blast radius, drift, compliance |
| Β | thothctl_cost_analysis |
AWS cost projections |
| Β | thothctl_drift_detection |
Infrastructure drift detection |
| Workflow | thothctl_workflow_devsecops |
Run DevSecOps SDLC phases |
| Β | thothctl_workflow_run |
Execute custom YAML DAG workflows |
| Inventory | thothctl_inventory_iac |
SBOM, dependencies, version checking |
| Project | thothctl_init_project |
Initialize project from scaffold |
| Β | thothctl_init_space |
Create organizational space |
| Β | thothctl_init_env |
Bootstrap development environment |
| Β | thothctl_remove_project |
Remove a project |
| Β | thothctl_remove_space |
Remove a space |
| Β | thothctl_list_projects |
List managed projects |
| Β | thothctl_list_spaces |
List organizational spaces |
| Β | thothctl_list_templates |
List available templates |
| Β | thothctl_project_cleanup |
Clean temporary files |
| Β | thothctl_project_convert |
Convert project β template |
| Docs | thothctl_document_iac |
Auto-generate documentation |
| Ops | thothctl_check_project |
Project structure validation |
| Β | thothctl_check_environment |
Dev environment verification |
| Β | thothctl_quickstart |
Guided onboarding wizard |
| Β | thothctl_upgrade |
Upgrade ThothCTL |
| Β | thothctl_version |
Version info |
.thothcf.toml)[ai_review]
provider = "ollama" # ollama | bedrock | openai | azure
model = "llama3.1:8b" # Model name (provider-specific)
[ai_review.budget]
daily_limit_tokens = 1000000 # Daily token budget
monthly_limit_usd = 50.00 # Monthly cost cap
auto_fallback = true # Fall back to offline on budget exceeded
[ai_review.safety]
require_human_approval = true # Require human for PR decisions
min_confidence = 0.85 # Minimum confidence for auto-decisions
| Variable | Purpose | Default |
|---|---|---|
OLLAMA_HOST |
Ollama server URL | http://localhost:11434 |
AWS_REGION |
AWS region for Bedrock | us-east-1 |
OPENAI_API_KEY |
OpenAI API key | β |
AZURE_OPENAI_ENDPOINT |
Azure OpenAI endpoint | β |
THOTH_ORG_POLICY |
Git URL for org policies (OPA/Rego) | β |
| Situation | Approach | Command |
|---|---|---|
| βI need new infrastructureβ | Generate from intent | generate iac --intent "..." --provider ollama |
| βIs this PR safe to merge?β | AI review + decide | ai-review decide --pr-number 42 |
| βRun all checks before deployβ | Workflow pipeline | workflow devsecops --phase pre-deploy |
| βWhat will this cost?β | Cost analysis | check iac -type cost-analysis |
| βIs production drifting?β | Drift detection | check iac -type drift |
| βExplain findings and fix themβ | AI assistant via MCP | Chat: βReview scan results and fix issuesβ |
| βFull audit for complianceβ | Workflow + scanning | workflow devsecops --phase all --enforcement hard |
thothctl generate iac --intent "S3 bucket with encryption" --project-type terraform --provider ollama --applythothctl ai-review analyze -d . -p ollamathothctl workflow devsecops --phase securethothctl dashboard launch