Windows Installation Guide¶

ThothCTL fully supports Windows 10 and Windows 11 with native PowerShell integration.

Prerequisites¶

Required Software¶

Python 3.8 or higher

# Check Python version
python --version

If Python is not installed, download from python.org or install via Chocolatey:

choco install python

Git (optional, for version control features)
```
choco install git
```
Graphviz (optional, for dependency graphs)
```
choco install graphviz
```

External Tools (Optional)¶

Install these tools based on your use case:

Terraform/OpenTofu: For IaC operations

choco install terraform
# or
choco install opentofu

Checkov: For security scanning
```
pip install checkov
```
Trivy: For vulnerability scanning
```
choco install trivy
```
Terraform-docs: For documentation generation
```
choco install terraform-docs
```

Installation¶

Install from PyPI¶

# Install ThothCTL
pip install thothctl

# Verify installation
thothctl --version

Install from Source¶

# Clone repository
git clone https://github.com/thothforge/thothctl.git
cd thothctl

# Install in development mode
pip install -e .

# Verify installation
thothctl --version

Configuration¶

PowerShell Autocomplete¶

Enable command autocompletion in PowerShell:

# Run the autocomplete setup
thothctl-register-autocomplete

# Follow the prompts to add to your PowerShell profile

Alternatively, manually add to your PowerShell profile:

# Open PowerShell profile
notepad $PROFILE

# Add this line:
Register-ArgumentCompleter -Native -CommandName thothctl -ScriptBlock { param($wordToComplete, $commandAst, $cursorPosition); $env:_THOTHCTL_COMPLETE="powershell_complete"; $env:COMP_WORDS=$commandAst.ToString(); $env:COMP_CWORD=$cursorPosition; thothctl 2>$null }

# Reload profile
. $PROFILE

Configuration Directory¶

ThothCTL stores configuration in:

%LOCALAPPDATA%\thothctl

Typically: C:\Users\<YourUsername>\AppData\Local\thothctl

Verify Installation¶

Run the Windows compatibility test:

# Download and run the test script
python test_windows_compatibility.py

Expected output:

🪟 ThothCTL Windows Compatibility Test
========================================
🔍 Testing platform detection...
   Platform: Windows
   is_windows(): True
   Config dir: C:\Users\...\AppData\Local\thothctl
   Executable name (terraform): terraform.exe
   ✅ Platform detection works

📦 Testing imports...
   ✅ CLI UI imports work
   ✅ Common imports work
   ✅ Scanner imports work

📁 Testing config directory...
   Config directory: C:\Users\...\AppData\Local\thothctl
   ✅ Config directory created successfully

🔧 Testing autocomplete...
   ✅ Autocomplete module imports successfully
   💡 Run 'thothctl-register-autocomplete' to set up PowerShell completion

========================================
📊 Results: 4/4 tests passed
🎉 All tests passed! ThothCTL should work on Windows.

Quick Start¶

Initialize a Space¶

# Create a new space
thothctl init space -s my-space -ot terragrunt -vcs github

# Verify space creation
thothctl list spaces

Initialize a Project¶

# Create a new project
thothctl init project -p my-project -s my-space

# Navigate to project
cd my-project

Scan Infrastructure¶

# Scan Terraform code
thothctl scan iac --directory .\terraform

# Scan with specific tools
thothctl scan iac --directory .\terraform --tools checkov,trivy

Create Inventory¶

# Generate inventory with version checking
thothctl inventory iac --check-versions

# Generate HTML report
thothctl inventory iac --check-versions --report-type html

Common Issues¶

Issue: Command Not Found¶

Problem: thothctl command not recognized

Solution:

# Ensure Python Scripts directory is in PATH
$env:Path += ";$env:LOCALAPPDATA\Programs\Python\Python3XX\Scripts"

# Or reinstall with --user flag
pip install --user thothctl

Issue: External Tool Not Found¶

Problem: "terraform.exe not found in PATH"

Solution:

# Verify tool is installed
where.exe terraform

# If not found, install via Chocolatey
choco install terraform

# Refresh environment variables
refreshenv

Issue: Permission Denied¶

Problem: Cannot create config directory

Solution:

# Run PowerShell as Administrator
# Or manually create directory
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\thothctl"

Issue: Import Errors¶

Problem: Module import failures

Solution:

# Reinstall with all dependencies
pip uninstall thothctl
pip install thothctl

# Or install from source
pip install -e .

Path Handling¶

ThothCTL automatically handles Windows path formats:

# All these work correctly
thothctl scan iac --directory .\terraform
thothctl scan iac --directory C:\projects\terraform
thothctl scan iac --directory \\network\share\terraform

Environment Variables¶

Set environment variables for ThothCTL:

# Enable debug mode
$env:THOTHCTL_DEBUG = "true"

# Set custom config directory
$env:THOTH_CONFIG_DIR = "C:\custom\path"

# Set log level
$env:THOTH_LOG_LEVEL = "DEBUG"

Next Steps¶

Support¶

For Windows-specific issues: - Check GitHub Issues - Review Troubleshooting Guide - Join community discussions