Skip to main content

​
Overview

The Dex CLI uses a workspace configuration system to manage multiple Git repositories and coordinate development across the site and api repos. This configuration lives outside your project directories and persists across terminal sessions.
The workspace config is stored in ~/.config/dexdsl/workspaces.json (or %APPDATA%/dexdsl/workspaces.json on Windows).

​
Configuration Structure

The workspace configuration is a JSON file with the following structure: 
{
  "version": "dex-workspaces-v1",
  "updatedAt": "2026-03-07T10:30:00.000Z",
  "defaultRepo": "site",
  "repos": {
    "site": {
      "root": "/Users/staff/dexdsl/site"
    },
    "api": {
      "root": "/Users/staff/dexdsl/api"
    }
  }
}

​
Configuration Fields

​
version
string
required
Always dex-workspaces-v1. Used for future schema migrations.
​
updatedAt
ISO timestamp
required
Last modification timestamp. Automatically updated on writes.
​
defaultRepo
'site' | 'api'
required
Which repository to use when a command doesn’t specify --repo.
​
repos
object
required
Map of repository keys to configuration objects. Each repo must have a root property pointing to an absolute path.

​
Environment Variables

You can override workspace behavior with environment variables:
VariablePurposeExample
DEX_CONFIG_DIRCustom config directory~/dex-config
DEX_WORKSPACE_FILEDirect path to workspace file~/my-workspace.json
Environment variable paths must be absolute or use ~ for home directory.

​
Setup and Validation

​
Initial Setup

Run the setup wizard to configure your workspace: 
dex setup
The wizard will:
  1. Prompt for the site repo path
  2. Prompt for the api repo path
  3. Validate that both paths are Git repositories
  4. Write the configuration to disk
  5. Display the active workspace context

​
Resetting Configuration

To reconfigure your workspace from scratch: 
dex setup --reset
This clears existing configuration and re-runs the setup wizard.

​
Validation Rules

The workspace validator enforces:
1

Path Resolution

All paths must be absolute and normalized (no ./ or ../).
2

Directory Existence

Each configured path must exist on the filesystem.
3

Git Repository Check

Each path must be a valid Git repository root (contains .git or passes git rev-parse --is-inside-work-tree).
4

Default Repo

The defaultRepo must be one of the configured repository keys.

​
Workspace Resolution

When you run a Dex command, the CLI resolves the active repository root:

​
Example Resolution

Given this workspace config: 
{
  "defaultRepo": "site",
  "repos": {
    "site": { "root": "/home/user/dexdsl/site" },
    "api": { "root": "/home/user/dexdsl/api" }
  }
}
  • dex init → uses /home/user/dexdsl/site
  • dex init --repo api → uses /home/user/dexdsl/api
  • dex init --repo invalid → falls back to /home/user/dexdsl/site

​
Source Code Reference

The workspace configuration system is implemented in scripts/lib/dex-workspace-config.mjs: 
export async function readWorkspaceConfig({ filePath } = {}) {
  const targetPath = filePath ? path.resolve(filePath) : getWorkspaceConfigPath();
  try {
    const source = await fs.readFile(targetPath, 'utf8');
    const parsed = JSON.parse(source);
    const config = normalizeWorkspaceConfig(parsed);
    const validation = await validateWorkspaceConfig(config);
    return {
      filePath: targetPath,
      exists: true,
      config,
      ok: validation.ok,
      issues: validation.issues,
    };
  } catch (error) {
    // Handle ENOENT...
  }
}
See scripts/lib/dex-workspace-config.mjs for the complete implementation including normalization, validation, and platform-specific config path resolution.

​
Troubleshooting

​
Config Not Found

If you see “workspace config not found”: 
# Run setup to create the config
dex setup

​
Invalid Git Repository

If a path fails Git validation:
  1. Verify the directory exists: ls /path/to/repo
  2. Check for .git directory: ls -la /path/to/repo/.git
  3. Test Git: git -C /path/to/repo status

​
Permission Issues

If you can’t write to the config directory: 
# Use a custom config location
export DEX_CONFIG_DIR=~/my-config
dex setup

​
Best Practices

Single Source of Truth

Keep one workspace config per development machine. Don’t commit workspaces.json to Git.

Absolute Paths

Always use absolute paths or ~ for home directory. Relative paths will cause resolution issues.

Validate After Clone

After cloning repos, run dex setup --reset to update paths for the new machine.

Team Consistency

Document expected repo structure in team README so everyone uses consistent naming.

Build docs developers (and LLMs) love

Get started for freeTalk to us