The space command manages ThothCTL spaces — logical contexts that group configuration, credentials, VCS providers, and governance policies. Spaces enable multi-team and multi-environment workflows.
Spaces provide:
| Subcommand | Description |
|---|---|
activate |
Set a space as the active context |
deactivate |
Clear the active space context |
show |
Display space configuration summary |
update |
Modify space settings (policy repo, VCS, tools) |
# Activate a space
thothctl space activate my-space
# Deactivate (clear active space)
thothctl space deactivate
# Show space configuration
thothctl space show my-space
# Update space settings
thothctl space update my-space --policy-repo https://github.com/myorg/policies.git
thothctl space update my-space --vcs-provider azure_repos
thothctl space update my-space --orchestration-tool terragrunt
Set a space as the active context. All subsequent commands use this space for credential resolution and defaults.
thothctl space activate <SPACE_NAME>
Effect:
~/.thothcf/active_space--space is specified--post-to-pr) use this space’s stored PATExample:
$ thothctl space activate lab-azure
🌐 Active space set to 'lab-azure'
New projects will use this space by default unless --space is specified.
Clear the active space context. After deactivation, commands that require a space will need an explicit --space flag or will fall back to project-level configuration.
thothctl space deactivate
Effect:
~/.thothcf/active_space file (or clears its content)--space flag or fail with “no space configured”Example:
$ thothctl space deactivate
🔓 Active space cleared. No space is currently active.
Use 'thothctl space activate <name>' to set a new active space.
Display the full configuration of a space.
thothctl space show <SPACE_NAME>
Displays:
Modify space configuration settings.
thothctl space update <SPACE_NAME> [OPTIONS]
| Option | Type | Description |
|---|---|---|
-pr, --policy-repo |
Text | Git URL or local path for organization policies |
-tr, --terraform-registry |
Text | Terraform registry URL |
-ot, --orchestration-tool |
Choice | terragrunt, terramate, or none |
-vcs, --vcs-provider |
Choice | azure_repos, github, or gitlab |
-d, --description |
Text | Space description |
Examples:
# Set organization policy repository
thothctl space update production --policy-repo https://github.com/myorg/iac-policies.git
# Change VCS provider
thothctl space update production --vcs-provider github
# Set orchestration tool
thothctl space update production --orchestration-tool terragrunt
# Update Terraform registry (private registry)
thothctl space update production --terraform-registry https://app.terraform.io
All space configuration is stored in ~/.thothcf/spaces.toml (single source of truth). Space directories contain only operational files:
~/.thothcf/
├── spaces.toml # Single source of truth for all space config
├── active_space # Currently active space name (plain text file)
└── spaces/
└── <space-name>/
├── metadata.toml # Directory identification (name, created_at, config_source)
├── credentials/ # Encrypted VCS/TF/cloud credentials (.enc files)
├── configs/ # Space-level policy overrides
│ └── scan_policy.toml # Scan enforcement + supply chain thresholds
├── vcs/ # Provider-specific config (github.toml, etc.)
├── terraform/ # Registry config (registry.toml)
└── orchestration/ # Tool config (terragrunt.toml, etc.)
[spaces.production]
name = "production"
description = "Production infrastructure"
created_at = "2026-07-01T10:05:00"
[spaces.production.version_control]
provider = "github"
[spaces.production.terraform]
registry = "https://app.terraform.io"
auth_method = "token"
[spaces.production.orchestration]
tool = "terragrunt"
[spaces.production.governance]
policy_repo = "https://github.com/myorg/iac-policies.git"
[spaces.production.projects]
[spaces.production.projects.vpc-stack]
registered_at = "2026-07-05T11:00:00"
vcs/azure_repos.toml)provider = "azure_repos"
[settings]
organization = "myorg"
project = "infrastructure"
repository = "iac-modules"
branch = "main"
auth_method = "pat"
vcs/github.toml)provider = "github"
[settings]
organization = "myorg"
repository = "infrastructure"
branch = "main"
auth_method = "pat"
Spaces are created with thothctl init space:
# Interactive creation
thothctl init space --name production
# Non-interactive creation (CI/CD)
THOTH_SPACE_TOKEN=ghp_xxxx \
THOTH_SPACE_ORG=myorg \
THOTH_SPACE_PASSWORD=secret \
thothctl init space --name production --vcs-provider github
When a command needs VCS credentials (e.g., --post-to-pr, --reuse for templates):
1. Check --space flag → use that space
2. Check active space (~/.thothcf/active_space) → use active
3. Check project .thothcf.toml [thothcf] space field → use project's space
4. Fail with "no space configured"
When thothctl scan iac -t opa needs policies:
1. Check --policy-dir flag → explicit path/URL
2. Check THOTH_ORG_POLICY env var → URL
3. Check active space → governance.policy_repo field
4. Check local ./policy directory → default
When --post-to-pr is used:
1. Detect CI environment (Azure Pipelines, GitHub Actions)
2. Resolve space credentials for the VCS provider
3. Post scan summary as PR comment using the stored PAT
# Create spaces for each environment
thothctl init space --name dev
thothctl init space --name staging
thothctl init space --name production
# Activate for current work
thothctl space activate dev
# Deactivate when done
thothctl space deactivate
# Override for specific commands
thothctl scan iac --post-to-pr --space production
# Bind org policies to a space
thothctl space update production \
--policy-repo https://github.com/myorg/iac-policies.git
# Now any scan in this space auto-uses org policies
thothctl space activate production
thothctl scan iac -t opa # Uses org policies automatically