Commands & Hooks
Named commands
Anything under [commands] becomes a run target.
[commands.dev]
run = "pnpm dev"
cwd = "packages/app"
[commands.dev.env]
NODE_OPTIONS = "--max-old-space-size=8192"
[commands.test]
run = "pnpm test"
uxd my-project 42 run dev
uxd my-project 42 run test -- --watch
| Key | Type | Meaning |
|---|---|---|
run | string | required — the command, templated, executed through a shell |
cwd | string | Optional, relative to the worktree root |
env | table | Optional, merged over the project's [env] for this command only |
Arguments after -- are appended to run, so run test -- --watch executes
pnpm test --watch.
list, sync, info — the
built-in takes precedence and your command becomes unreachable. uxd doctor
warns about the shadowing.default_command
default_command = "dev"
makes uxd my-project 42 behave like uxd my-project 42 run dev. It accepts
either a verb or a configured command name.
Hooks
Four lifecycle hooks, all optional, all templated, each executed as
bash -c "<script>" with the worktree as the working directory and the full
UXD_* environment.
[hooks]
post_checkout = "echo 'workspace ready: {path}'"
pre_run = "docker compose up -d"
post_sync = "pnpm install --frozen-lockfile"
pre_clean = "docker compose down"
| Hook | Fires | If it exits non-zero |
|---|---|---|
post_checkout | After a workspace is materialized | Fails the command — E_SETUP, exit 6 |
pre_run | Before run, exec or shell executes | Fails the command — E_SETUP, exit 6 |
post_sync | After sync resets the worktree | Warns and continues |
pre_clean | Before a workspace is removed | Warns and skips that removal |
post_checkout runs on every fresh workspace
and pre_run runs on every single run, exec and shell.pre_clean is the place to release resources a workspace acquired — stop a
container, drop a scratch database — since after clean the directory is gone.
Because a failing pre_clean skips the removal, it also works as a veto:
warning: pre_clean hook failed for feat-login — skipping
Under --dry-run, hooks are printed as the bash -c line that would run, and
nothing executes.
Ordering
For a uxd my-project 42 run dev on a fresh ref:
- Resolve the ref, create the worktree.
post_checkout[setup]— seed files, thenrunif thecache_keyhash changed.pre_runcommands.dev.run
Preview steps 3–5 without executing them:
uxd my-project 42 run dev --dry-run