Skip to main content
Interactive wizard to configure local repository roots for the site and API repos.

​
Usage

dex setup [--reset] [--repo site|api]

​
Flags

​
—reset

Reset and reconfigure existing workspace configuration. 
dex setup --reset
If workspace roots are already configured, --reset prompts you to reconfigure both repositories from scratch.

​
—repo

Specify which repository context to use as the default. 
dex setup --repo site
dex setup --repo api
Default: site This determines which repository Dex commands target by default when --repo is not explicitly passed to other commands.

​
First-time setup

When you run dex setup for the first time, the wizard guides you through:
1

Confirmation prompt

Confirms you want to configure workspace roots for both repositories.
2

Site repo (dexdsl.github.io)

Choose to use an existing local path or clone the repository via GitHub CLI.
3

API repo (dex-api)

Choose to use an existing local path or clone the repository via GitHub CLI.
4

Default repo selection

Choose whether site or api is the default repo for Dex commands.
5

Write config

Writes workspace configuration to ~/.config/dexdsl/workspaces.json.

​
Configuration modes

For each repository, you can:

​
Use existing local repo path

Provides a prompt to enter the absolute path to an existing local repository. Validation:
  • Path must exist
  • Must be a valid git repository (contains .git/)
  • Must be a repository root (not a subdirectory)

​
Clone repository (guided)

Requires GitHub CLI (gh) to be installed and authenticated.
If gh is not authenticated, the wizard prompts: 
GitHub CLI is not authenticated. Run gh auth login now?
If you confirm, the wizard runs gh auth login interactively. After authentication, you provide:
  1. Repo URL - Full GitHub repo URL (e.g., https://github.com/user/repo.git)
  2. Parent directory - Where to clone the repo (e.g., ~/projects)
  3. Folder name - Name of the cloned directory (auto-inferred from URL)
The wizard runs: 
gh repo clone <url> <parent>/<folder>
Then validates the cloned repository.

​
Workspace config file

Setup writes configuration to: 
~/.config/dexdsl/workspaces.json
Structure: 
{
  "repos": {
    "site": {
      "root": "/Users/you/projects/dexdsl.github.io"
    },
    "api": {
      "root": "/Users/you/projects/dex-api"
    }
  },
  "defaultRepo": "site"
}

​
Config overrides

You can override the config file location with environment variables: Explicit config file path: 
export DEX_WORKSPACE_FILE=~/custom/workspaces.json
Alternate config home directory: 
export DEX_CONFIG_DIR=~/.dex
With DEX_CONFIG_DIR, the config file becomes $DEX_CONFIG_DIR/dexdsl/workspaces.json.

​
Workspace resolution

When you run any Dex command, workspace resolution works as follows:
  1. Read workspace config from file
  2. Determine active repo (explicit --repo flag, or defaultRepo from config)
  3. Resolve active repo root from config
  4. Change working directory (chdir) to repo root
  5. Execute command in that context
All Dex commands operate in the context of the resolved workspace root. You do NOT need to cd into the repo directory manually.

​
Default repo URLs

During setup, the wizard auto-detects default URLs from: Site repo:
  1. $DEX_SITE_REPO_URL environment variable
  2. git config --get remote.origin.url in the Dex script directory
API repo:
  1. $DEX_API_REPO_URL environment variable
  2. Inferred from site repo URL by replacing dexdsl.github.io with dex-api

​
Non-interactive fallback

If Dex is run in a non-interactive environment (no TTY) without a valid workspace config:
  • Dex falls back to the current working directory
  • Prints guidance to run dex setup manually
  • Commands may fail if they require workspace-specific paths

​
Examples

​
First-time setup

dex setup
Runs the interactive wizard to configure both repositories.

​
Reset existing configuration

dex setup --reset
Reconfigures workspace roots, discarding the existing configuration.

​
Set API as default repo

dex setup --repo api
During setup, selects api as the default repo for Dex commands.

​
Override config location

export DEX_WORKSPACE_FILE=~/my-workspace.json
dex setup
Writes configuration to ~/my-workspace.json instead of the default location.

​
Troubleshooting

​
Workspace config canceled

If you cancel setup partway through: 
Workspace setup cancelled.
Solution: Re-run dex setup to complete configuration.

​
GitHub CLI not installed

GitHub CLI (gh) is not installed. Install gh or choose existing local path.
Solution:
  1. Install gh from https://cli.github.com/
  2. Or choose “Use existing local repo path” during setup

​
gh auth login failed

gh auth login failed. Please retry or choose existing local path.
Solution:
  1. Run gh auth login manually in your terminal
  2. Or choose “Use existing local repo path” during setup

​
Invalid repo path

Path must be a git repository root.
Solution: Provide the absolute path to the repository root directory (the directory containing .git/).

​
Operational behavior

1

Auto-resolve workspace root

Dex automatically resolves the active repo root from workspace config before executing commands.
2

Change directory

Dex changes the working directory (chdir) to the repo root.
3

Execute command

The command runs in the context of the repo root.
This means:
  • You can run dex commands from any directory
  • You do NOT need to manually cd into the repo
  • All relative paths in Dex commands are relative to the repo root

dex deploy

Deploy changes from configured workspace

Workspace Concepts

Learn about workspace configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us