Configuration
Project File
Every key a uxd project TOML accepts — repository, behavior, setup — with types, defaults, and what happens when you omit them.
One file per project at <config-dir>/<project>.toml. The filename is the
project name.
A complete example
~/.uxd/my-project.toml
repo = "git@github.com:my-org/my-project.git"
default_branch = "main"
editor = "zed"
ports = 2
base_port = 5700
[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]
[env]
PORT = "{port}"
API_PORT = "{port+1}"
[commands.dev]
run = "pnpm dev"
Repository
| Key | Type | Default |
|---|---|---|
repo | string | required — ssh or https URL |
repo_path | path | {root}/{project}/repo |
worktrees_path | path | {root}/{project}/trees |
default_branch | string | auto-detected from origin HEAD |
{root} comes from defaults.root. Path values support a leading ~ only —
no other expansion.
Behavior
| Key | Type | Default |
|---|---|---|
editor | string | defaults.editor — a preset name or a template |
default_command | string | defaults.default_command — a verb or a configured command name |
ports | integer 1–10 | 1 — contiguous ports allocated per workspace |
base_port | integer 1024–65000 | derived per project |
See Editors for the preset list, and
Run dev servers in parallel for how
ports and base_port interact.
[setup]
Runs after checkout and before run, exec or shell. Omit the table
entirely and no setup happens.
[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]
seed_from = "~/dev/my-project"
| Key | Type | Meaning |
|---|---|---|
run | string | The setup command, templated. Skipped entirely when absent |
cache_key | string | Globs; setup re-runs when their hash changes |
seed_files | string | Relative paths copied into a new worktree |
seed_from | path | An extra seed source, checked before seeds/<project>/ |
uxd hashes the files matched by cache_key. If the hash is unchanged since
the last successful setup for that workspace, run is skipped. Without a
cache_key, setup runs every time.Seeding is covered in Seed local files.
Strictness
The schema is strict — an unknown key is an error, not a warning. That
catches typos like worktree_path immediately instead of silently ignoring
them.
uxd config validate my-project
Errors are reported in aggregate, so one run shows you every problem in the file.