# Workspace Configuration Management Commands\n\n## Overview\n\nThe workspace configuration management commands provide a comprehensive set of tools for viewing, editing, validating, and managing workspace configurations.\n\n## Command Summary\n\n| Command | Description |\n| --------- | ------------- |\n| `workspace config show` | Display workspace configuration |\n| `workspace config validate` | Validate all configuration files |\n| `workspace config generate provider` | Generate provider configuration from template |\n| `workspace config edit` | Edit configuration files |\n| `workspace config hierarchy` | Show configuration loading hierarchy |\n| `workspace config list` | List all configuration files |\n\n## Commands\n\n### Show Workspace Configuration\n\nDisplay the complete workspace configuration in JSON, YAML, TOML, and other formats.\n\n```\n# Show active workspace config (YAML format)\nprovisioning workspace config show\n\n# Show specific workspace config\nprovisioning workspace config show my-workspace\n\n# Show in JSON format\nprovisioning workspace config show --out json\n\n# Show in TOML format\nprovisioning workspace config show --out toml\n\n# Show specific workspace in JSON\nprovisioning workspace config show my-workspace --out json\n```\n\n**Output:** Complete workspace configuration in the specified format\n\n### Validate Workspace Configuration\n\nValidate all configuration files for syntax and required sections.\n\n```\n# Validate active workspace\nprovisioning workspace config validate\n\n# Validate specific workspace\nprovisioning workspace config validate my-workspace\n```\n\n**Checks performed:**\n\n- Main config (`provisioning.yaml`) - YAML syntax and required sections\n- Provider configs (`providers/*.toml`) - TOML syntax\n- Platform service configs (`platform/*.toml`) - TOML syntax\n- KMS config (`kms.toml`) - TOML syntax\n\n**Output:** Validation report with success/error indicators\n\n### Generate Provider Configuration\n\nGenerate a provider configuration file from a template.\n\n```\n# Generate AWS provider config for active workspace\nprovisioning workspace config generate provider aws\n\n# Generate UpCloud provider config for specific workspace\nprovisioning workspace config generate provider upcloud --infra my-workspace\n\n# Generate local provider config\nprovisioning workspace config generate provider local\n```\n\n**What it does:**\n\n1. Locates provider template in `extensions/providers/{name}/config.defaults.toml`\n2. Interpolates workspace-specific values (`{{workspace.name}}`, `{{workspace.path}}`)\n3. Saves to `{workspace}/config/providers/{name}.toml`\n\n**Output:** Generated configuration file ready for customization\n\n### Edit Configuration Files\n\nOpen configuration files in your editor for modification.\n\n```\n# Edit main workspace config\nprovisioning workspace config edit main\n\n# Edit specific provider config\nprovisioning workspace config edit provider aws\n\n# Edit platform service config\nprovisioning workspace config edit platform orchestrator\n\n# Edit KMS config\nprovisioning workspace config edit kms\n\n# Edit for specific workspace\nprovisioning workspace config edit provider upcloud --infra my-workspace\n```\n\n**Editor used:** Value of `$EDITOR` environment variable (defaults to `vi`)\n\n**Config types:**\n\n- `main` - Main workspace configuration (`provisioning.yaml`)\n- `provider <name>` - Provider configuration (`providers/{name}.toml`)\n- `platform <name>` - Platform service configuration (`platform/{name}.toml`)\n- `kms` - KMS configuration (`kms.toml`)\n\n### Show Configuration Hierarchy\n\nDisplay the configuration loading hierarchy and precedence.\n\n```\n# Show hierarchy for active workspace\nprovisioning workspace config hierarchy\n\n# Show hierarchy for specific workspace\nprovisioning workspace config hierarchy my-workspace\n```\n\n**Output:** Visual hierarchy showing:\n\n1. Environment Variables (highest priority)\n2. User Context\n3. Platform Services\n4. Provider Configs\n5. Workspace Config (lowest priority)\n\n### List Configuration Files\n\nList all configuration files for a workspace.\n\n```\n# List all configs\nprovisioning workspace config list\n\n# List only provider configs\nprovisioning workspace config list --type provider\n\n# List only platform configs\nprovisioning workspace config list --type platform\n\n# List only KMS config\nprovisioning workspace config list --type kms\n\n# List for specific workspace\nprovisioning workspace config list my-workspace --type all\n```\n\n**Output:** Table of configuration files with type, name, and path\n\n## Workspace Selection\n\nAll config commands support two ways to specify the workspace:\n\n1. **Active Workspace** (default):\n\n   ```bash\n   provisioning workspace config show\n   ```\n\n1. **Specific Workspace** (using `--infra` flag):\n\n   ```bash\n   provisioning workspace config show --infra my-workspace\n   ```\n\n## Configuration File Locations\n\nWorkspace configurations are organized in a standard structure:\n\n```\n{workspace}/\n├── config/\n│   ├── provisioning.yaml       # Main workspace config\n│   ├── providers/              # Provider configurations\n│   │   ├── aws.toml\n│   │   ├── upcloud.toml\n│   │   └── local.toml\n│   ├── platform/               # Platform service configs\n│   │   ├── orchestrator.toml\n│   │   ├── control-center.toml\n│   │   └── mcp.toml\n│   └── kms.toml                # KMS configuration\n```\n\n## Configuration Hierarchy\n\nConfiguration values are loaded in the following order (highest to lowest priority):\n\n1. **Environment Variables** - `PROVISIONING_*` variables\n2. **User Context** - `~/Library/Application Support/provisioning/ws_{name}.yaml`\n3. **Platform Services** - `{workspace}/config/platform/*.toml`\n4. **Provider Configs** - `{workspace}/config/providers/*.toml`\n5. **Workspace Config** - `{workspace}/config/provisioning.yaml`\n\nHigher priority values override lower priority values.\n\n## Examples\n\n### Complete Workflow\n\n```\n# 1. Create new workspace with activation\nprovisioning workspace init my-project ~/workspaces/my-project --providers [aws,local] --activate\n\n# 2. Validate configuration\nprovisioning workspace config validate\n\n# 3. View configuration hierarchy\nprovisioning workspace config hierarchy\n\n# 4. Generate additional provider config\nprovisioning workspace config generate provider upcloud\n\n# 5. Edit provider settings\nprovisioning workspace config edit provider upcloud\n\n# 6. List all configs\nprovisioning workspace config list\n\n# 7. Show complete config in JSON\nprovisioning workspace config show --out json\n\n# 8. Validate everything\nprovisioning workspace config validate\n```\n\n### Multi-Workspace Management\n\n```\n# Create multiple workspaces\nprovisioning workspace init dev ~/workspaces/dev --activate\nprovisioning workspace init staging ~/workspaces/staging\nprovisioning workspace init prod ~/workspaces/prod\n\n# Validate specific workspace\nprovisioning workspace config validate staging\n\n# Show config for production\nprovisioning workspace config show prod --out yaml\n\n# Edit provider for specific workspace\nprovisioning workspace config edit provider aws --infra prod\n```\n\n### Configuration Troubleshooting\n\n```\n# 1. Validate all configs\nprovisioning workspace config validate\n\n# 2. If errors, check hierarchy\nprovisioning workspace config hierarchy\n\n# 3. List all config files\nprovisioning workspace config list\n\n# 4. Edit problematic config\nprovisioning workspace config edit provider aws\n\n# 5. Validate again\nprovisioning workspace config validate\n```\n\n## Integration with Other Commands\n\nConfig commands integrate seamlessly with other workspace operations:\n\n```\n# Create workspace with providers\nprovisioning workspace init my-app ~/apps/my-app --providers [aws,upcloud] --activate\n\n# Generate additional configs\nprovisioning workspace config generate provider local\n\n# Validate before deployment\nprovisioning workspace config validate\n\n# Deploy infrastructure\nprovisioning server create --infra my-app\n```\n\n## Tips\n\n1. **Always validate after editing**: Run `workspace config validate` after manual edits\n\n2. **Use hierarchy to understand precedence**: Run `workspace config hierarchy` to see which config files are being used\n\n3. **Generate from templates**: Use `config generate provider` rather than creating configs manually\n\n4. **Check before activation**: Validate a workspace before activating it as default\n\n5. **Use --out json for scripting**: JSON output is easier to parse in scripts\n\n## See Also\n\n- [Workspace Initialization](workspace-initialization.md)\n- [Provider Configuration](provider-configuration.md)\n- Configuration Architecture
