provisioning/docs/src/infrastructure/workspaces/workspace-switching-guide.md

Workspace Switching Guide

Version: 1.0.0 Date: 2025-10-06 Status: ✅ Production Ready

Overview

The provisioning system now includes a centralized workspace management system that allows you to easily switch between multiple workspaces without manually editing configuration files.

Quick Start

List Available Workspaces

provisioning workspace list

Output:

Registered Workspaces:

  ● librecloud
      Path: /Users/Akasha/project-provisioning/workspace_librecloud
      Last used: 2025-10-06T12:29:43Z

    production
      Path: /opt/workspaces/production
      Last used: 2025-10-05T10:15:30Z

The green ● indicates the currently active workspace.

Check Active Workspace

provisioning workspace active

Output:

Active Workspace:
  Name: librecloud
  Path: /Users/Akasha/project-provisioning/workspace_librecloud
  Last used: 2025-10-06T12:29:43Z

Switch to Another Workspace

# Option 1: Using activate
provisioning workspace activate production

# Option 2: Using switch (alias)
provisioning workspace switch production

Output:

✓ Workspace 'production' activated

Current workspace: production
Path: /opt/workspaces/production

ℹ All provisioning commands will now use this workspace

Register a New Workspace

# Register without activating
provisioning workspace register my-project ~/workspaces/my-project

# Register and activate immediately
provisioning workspace register my-project ~/workspaces/my-project --activate

Remove Workspace from Registry

# With confirmation prompt
provisioning workspace remove old-workspace

# Skip confirmation
provisioning workspace remove old-workspace --force

Note: This only removes the workspace from the registry. The workspace files are NOT deleted.

Architecture

Central User Configuration

All workspace information is stored in a central user configuration file:

Location: ~/Library/Application Support/provisioning/user_config.yaml

Structure:

# Active workspace (current workspace in use)
active_workspace: "librecloud"

# Known workspaces (automatically managed)
workspaces:
  - name: "librecloud"
    path: "/Users/Akasha/project-provisioning/workspace_librecloud"
    last_used: "2025-10-06T12:29:43Z"

  - name: "production"
    path: "/opt/workspaces/production"
    last_used: "2025-10-05T10:15:30Z"

# User preferences (global settings)
preferences:
  editor: "vim"
  output_format: "yaml"
  confirm_delete: true
  confirm_deploy: true
  default_log_level: "info"
  preferred_provider: "upcloud"

# Metadata
metadata:
  created: "2025-10-06T12:29:43Z"
  last_updated: "2025-10-06T13:46:16Z"
  version: "1.0.0"

How It Works

1. Workspace Registration: When you register a workspace, it's added to the workspaces list in user_config.yaml

2. Activation: When you activate a workspace:

   • active_workspace is updated to the workspace name
   • The workspace's last_used timestamp is updated
   • All provisioning commands now use this workspace's configuration

3. Configuration Loading: The config loader reads active_workspace from user_config.yaml and loads:

   • workspace_path/config/provisioning.yaml
   • workspace_path/config/providers/*.toml
   • workspace_path/config/platform/*.toml
   • workspace_path/config/kms.toml

Advanced Features

User Preferences

You can set global user preferences that apply across all workspaces:

# Get a preference value
provisioning workspace get-preference editor

# Set a preference value
provisioning workspace set-preference editor "code"

# View all preferences
provisioning workspace preferences

Available Preferences:

• editor: Default editor for config files (vim, code, nano, etc.)
• output_format: Default output format (yaml, json, toml)
• confirm_delete: Require confirmation for deletions (true/false)
• confirm_deploy: Require confirmation for deployments (true/false)
• default_log_level: Default log level (debug, info, warn, error)
• preferred_provider: Preferred cloud provider (aws, upcloud, local)

Output Formats

List workspaces in different formats:

# Table format (default)
provisioning workspace list

# JSON format
provisioning workspace list --format json

# YAML format
provisioning workspace list --format yaml

Quiet Mode

Activate workspace without output messages:

provisioning workspace activate production --quiet

Workspace Requirements

For a workspace to be activated, it must have:

1. Directory exists: The workspace directory must exist on the filesystem

2. Config directory: Must have a config/ directory

   
   workspace_name/
   └── config/
       ├── provisioning.yaml  # Required
       ├── providers/         # Optional
       ├── platform/          # Optional
       └── kms.toml           # Optional
   
   

3. **Main config file**: Must have `config/provisioning.yaml`

If these requirements are not met, the activation will fail with helpful error messages:

✗ Workspace 'my-project' not found in registry 💡 Available workspaces: [list of workspaces] 💡 Register it first with: provisioning workspace register my-project

✗ Workspace is not migrated to new config system 💡 Missing: /path/to/workspace/config 💡 Run migration: provisioning workspace migrate my-project

## Migration from Old System

If you have workspaces using the old context system (`ws_{name}.yaml` files), they still work but you should register them in the new system:

Register existing workspace

provisioning workspace register old-workspace ~/workspaces/old-workspace

Activate it

provisioning workspace activate old-workspace

The old `ws_{name}.yaml` files are still supported for backward compatibility, but the new centralized system is recommended.

## Best Practices

### 1. **One Active Workspace at a Time**

Only one workspace can be active at a time. All provisioning commands use the active workspace's configuration.

### 2. **Use Descriptive Names**

Use clear, descriptive names for your workspaces:

✅ Good

provisioning workspace register production-us-east ~/workspaces/prod-us-east provisioning workspace register dev-local ~/workspaces/dev

❌ Avoid

provisioning workspace register ws1 ~/workspaces/workspace1 provisioning workspace register temp ~/workspaces/t

### 3. **Keep Workspaces Organized**

Store all workspaces in a consistent location:

~/workspaces/ ├── production/ ├── staging/ ├── development/ └── testing/

### 4. **Regular Cleanup**

Remove workspaces you no longer use:

List workspaces to see which ones are unused

provisioning workspace list

Remove old workspace

provisioning workspace remove old-workspace

### 5. **Backup User Config**

Periodically backup your user configuration:

cp "/Library/Application Support/provisioning/user_config.yaml" "/Library/Application Support/provisioning/user_config.yaml.backup"

## Troubleshooting

### Workspace Not Found

**Problem**: `✗ Workspace 'name' not found in registry`

**Solution**: Register the workspace first:

provisioning workspace register name /path/to/workspace

### Missing Configuration

**Problem**: `✗ Missing workspace configuration`

**Solution**: Ensure the workspace has a `config/provisioning.yaml` file. Run migration if needed:

provisioning workspace migrate name

### Directory Not Found

**Problem**: `✗ Workspace directory not found: /path/to/workspace`

**Solution**:

1. Check if the workspace was moved or deleted
2. Update the path or remove from registry:

provisioning workspace remove name provisioning workspace register name /new/path

### Corrupted User Config

**Problem**: `Error: Failed to parse user config`

**Solution**: The system automatically creates a backup and regenerates the config. Check:

ls -la "~/Library/Application Support/provisioning/user_config.yaml"*

Restore from backup if needed:

cp "/Library/Application Support/provisioning/user_config.yaml.backup.TIMESTAMP" "/Library/Application Support/provisioning/user_config.yaml"

## CLI Commands Reference

| Command | Alias | Description |
| --------- | ------- | ------------- |
| `provisioning workspace activate <name>` | - | Activate a workspace |
| `provisioning workspace switch <name>` | - | Alias for activate |
| `provisioning workspace list` | - | List all registered workspaces |
| `provisioning workspace active` | - | Show currently active workspace |
| `provisioning workspace register <name> <path>` | - | Register a new workspace |
| `provisioning workspace remove <name>` | - | Remove workspace from registry |
| `provisioning workspace preferences` | - | Show user preferences |
| `provisioning workspace set-preference <key> <value>` | - | Set a preference |
| `provisioning workspace get-preference <key>` | - | Get a preference value |

## Integration with Config System

The workspace switching system is fully integrated with the new target-based configuration system:

### Configuration Hierarchy (Priority: Low → High)

1. Workspace config workspace/{name}/config/provisioning.yaml
2. Provider configs workspace/{name}/config/providers/*.toml
3. Platform configs workspace/{name}/config/platform/*.toml
4. User context ~/Library/Application Support/provisioning/ws_{name}.yaml (legacy)
5. User config ~/Library/Application Support/provisioning/user_config.yaml (new)
6. Environment variables PROVISIONING_*

### Example Workflow

1. Create and activate development workspace

provisioning workspace register dev ~/workspaces/dev --activate

2. Work on development

provisioning server create web-dev-01 provisioning taskserv create kubernetes

3. Switch to production

provisioning workspace switch production

4. Deploy to production

provisioning server create web-prod-01 provisioning taskserv create kubernetes

5. Switch back to development

provisioning workspace switch dev

All commands now use dev workspace config

## Nickel Workspace Configuration

Starting with v3.7.0, workspaces use **Nickel** for type-safe, schema-validated configurations.

### Nickel Configuration Features

**Nickel Configuration** (Type-Safe):

{ workspace = { name = "myworkspace", version = "1.0.0", }, paths = { base = "/path/to/workspace", infra = "/path/to/workspace/infra", config = "/path/to/workspace/config", }, }

### Benefits of Nickel Configuration

- ✅ **Type Safety**: Catch configuration errors at load time, not runtime
- ✅ **Schema Validation**: Required fields, value constraints, format checking
- ✅ **Lazy Evaluation**: Only computes what's needed
- ✅ **Self-Documenting**: Records provide instant documentation
- ✅ **Merging**: Powerful record merging for composition

### Viewing Workspace Configuration

View your Nickel workspace configuration

provisioning workspace config show

View in different formats

provisioning workspace config show --format=yaml # YAML output provisioning workspace config show --format=json # JSON output provisioning workspace config show --format=nickel # Raw Nickel file

Validate configuration

provisioning workspace config validate

Output: ✅ Validation complete - all configs are valid

Show configuration hierarchy

provisioning workspace config hierarchy

## See Also

- **Configuration Guide**: `docs/architecture/adr/ADR-010-configuration-format-strategy.md`
- **Migration Guide**: [Nickel Migration](../architecture/adr/adr-011-nickel-migration.md)
- **From-Scratch Guide**: [From-Scratch Guide](../guides/from-scratch.md)
- **Nickel Patterns**: Nickel Language Module System

---

**Maintained By**: Infrastructure Team
**Version**: 2.0.0 (Updated for Nickel)
**Status**: ✅ Production Ready
**Last Updated**: 2025-12-03