# Workspace Configuration Management Commands

## Overview

The workspace configuration management commands provide a comprehensive set of tools for viewing, editing, validating, and managing workspace configurations.

## Command Summary

| Command | Description |
|---------|-------------|
| `workspace config show` | Display workspace configuration |
| `workspace config validate` | Validate all configuration files |
| `workspace config generate provider` | Generate provider configuration from template |
| `workspace config edit` | Edit configuration files |
| `workspace config hierarchy` | Show configuration loading hierarchy |
| `workspace config list` | List all configuration files |

## Commands

### Show Workspace Configuration

Display the complete workspace configuration in JSON, YAML, TOML, and other formats.

```bash
# Show active workspace config (YAML format)
provisioning workspace config show

# Show specific workspace config
provisioning workspace config show my-workspace

# Show in JSON format
provisioning workspace config show --out json

# Show in TOML format
provisioning workspace config show --out toml

# Show specific workspace in JSON
provisioning workspace config show my-workspace --out json
```plaintext

**Output:** Complete workspace configuration in the specified format

### Validate Workspace Configuration

Validate all configuration files for syntax and required sections.

```bash
# Validate active workspace
provisioning workspace config validate

# Validate specific workspace
provisioning workspace config validate my-workspace
```plaintext

**Checks performed:**

- Main config (`provisioning.yaml`) - YAML syntax and required sections
- Provider configs (`providers/*.toml`) - TOML syntax
- Platform service configs (`platform/*.toml`) - TOML syntax
- KMS config (`kms.toml`) - TOML syntax

**Output:** Validation report with success/error indicators

### Generate Provider Configuration

Generate a provider configuration file from a template.

```bash
# Generate AWS provider config for active workspace
provisioning workspace config generate provider aws

# Generate UpCloud provider config for specific workspace
provisioning workspace config generate provider upcloud --infra my-workspace

# Generate local provider config
provisioning workspace config generate provider local
```plaintext

**What it does:**

1. Locates provider template in `extensions/providers/{name}/config.defaults.toml`
2. Interpolates workspace-specific values (`{{workspace.name}}`, `{{workspace.path}}`)
3. Saves to `{workspace}/config/providers/{name}.toml`

**Output:** Generated configuration file ready for customization

### Edit Configuration Files

Open configuration files in your editor for modification.

```bash
# Edit main workspace config
provisioning workspace config edit main

# Edit specific provider config
provisioning workspace config edit provider aws

# Edit platform service config
provisioning workspace config edit platform orchestrator

# Edit KMS config
provisioning workspace config edit kms

# Edit for specific workspace
provisioning workspace config edit provider upcloud --infra my-workspace
```plaintext

**Editor used:** Value of `$EDITOR` environment variable (defaults to `vi`)

**Config types:**

- `main` - Main workspace configuration (`provisioning.yaml`)
- `provider <name>` - Provider configuration (`providers/{name}.toml`)
- `platform <name>` - Platform service configuration (`platform/{name}.toml`)
- `kms` - KMS configuration (`kms.toml`)

### Show Configuration Hierarchy

Display the configuration loading hierarchy and precedence.

```bash
# Show hierarchy for active workspace
provisioning workspace config hierarchy

# Show hierarchy for specific workspace
provisioning workspace config hierarchy my-workspace
```plaintext

**Output:** Visual hierarchy showing:

1. Environment Variables (highest priority)
2. User Context
3. Platform Services
4. Provider Configs
5. Workspace Config (lowest priority)

### List Configuration Files

List all configuration files for a workspace.

```bash
# List all configs
provisioning workspace config list

# List only provider configs
provisioning workspace config list --type provider

# List only platform configs
provisioning workspace config list --type platform

# List only KMS config
provisioning workspace config list --type kms

# List for specific workspace
provisioning workspace config list my-workspace --type all
```plaintext

**Output:** Table of configuration files with type, name, and path

## Workspace Selection

All config commands support two ways to specify the workspace:

1. **Active Workspace** (default):

   ```bash
   provisioning workspace config show
   ```

1. **Specific Workspace** (using `--infra` flag):

   ```bash
   provisioning workspace config show --infra my-workspace
   ```

## Configuration File Locations

Workspace configurations are organized in a standard structure:

```plaintext
{workspace}/
├── config/
│   ├── provisioning.yaml       # Main workspace config
│   ├── providers/              # Provider configurations
│   │   ├── aws.toml
│   │   ├── upcloud.toml
│   │   └── local.toml
│   ├── platform/               # Platform service configs
│   │   ├── orchestrator.toml
│   │   ├── control-center.toml
│   │   └── mcp.toml
│   └── kms.toml                # KMS configuration
```plaintext

## Configuration Hierarchy

Configuration values are loaded in the following order (highest to lowest priority):

1. **Environment Variables** - `PROVISIONING_*` variables
2. **User Context** - `~/Library/Application Support/provisioning/ws_{name}.yaml`
3. **Platform Services** - `{workspace}/config/platform/*.toml`
4. **Provider Configs** - `{workspace}/config/providers/*.toml`
5. **Workspace Config** - `{workspace}/config/provisioning.yaml`

Higher priority values override lower priority values.

## Examples

### Complete Workflow

```bash
# 1. Create new workspace with activation
provisioning workspace init my-project ~/workspaces/my-project --providers [aws,local] --activate

# 2. Validate configuration
provisioning workspace config validate

# 3. View configuration hierarchy
provisioning workspace config hierarchy

# 4. Generate additional provider config
provisioning workspace config generate provider upcloud

# 5. Edit provider settings
provisioning workspace config edit provider upcloud

# 6. List all configs
provisioning workspace config list

# 7. Show complete config in JSON
provisioning workspace config show --out json

# 8. Validate everything
provisioning workspace config validate
```plaintext

### Multi-Workspace Management

```bash
# Create multiple workspaces
provisioning workspace init dev ~/workspaces/dev --activate
provisioning workspace init staging ~/workspaces/staging
provisioning workspace init prod ~/workspaces/prod

# Validate specific workspace
provisioning workspace config validate staging

# Show config for production
provisioning workspace config show prod --out yaml

# Edit provider for specific workspace
provisioning workspace config edit provider aws --infra prod
```plaintext

### Configuration Troubleshooting

```bash
# 1. Validate all configs
provisioning workspace config validate

# 2. If errors, check hierarchy
provisioning workspace config hierarchy

# 3. List all config files
provisioning workspace config list

# 4. Edit problematic config
provisioning workspace config edit provider aws

# 5. Validate again
provisioning workspace config validate
```plaintext

## Integration with Other Commands

Config commands integrate seamlessly with other workspace operations:

```bash
# Create workspace with providers
provisioning workspace init my-app ~/apps/my-app --providers [aws,upcloud] --activate

# Generate additional configs
provisioning workspace config generate provider local

# Validate before deployment
provisioning workspace config validate

# Deploy infrastructure
provisioning server create --infra my-app
```plaintext

## Tips

1. **Always validate after editing**: Run `workspace config validate` after manual edits

2. **Use hierarchy to understand precedence**: Run `workspace config hierarchy` to see which config files are being used

3. **Generate from templates**: Use `config generate provider` rather than creating configs manually

4. **Check before activation**: Validate a workspace before activating it as default

5. **Use --out json for scripting**: JSON output is easier to parse in scripts

## See Also

- [Workspace Initialization](workspace-initialization.md)
- [Provider Configuration](provider-configuration.md)
- Configuration Architecture
