Workspace Verbs
These verbs take a project and a ref:
uxd <project> <ref> <verb> [flags] [-- passthrough]
checkout
Materializes the workspace and prints its path on stdout. This is the default verb, and the one to use from scripts.
uxd my-project feat/login checkout
→ fetching origin/feat/login
→ worktree ready: ~/dev/uxd/my-project/trees/feat-login
| Flag | Effect |
|---|---|
--fetch | Force a re-fetch before materializing |
--setup | Also run [setup] (off by default for checkout) |
--no-setup | Skip [setup] |
--json | Print a result object instead of the path |
uxd my-project feat/login checkout --json
{"project":"my-project","slug":"feat-login","ref":"feat/login","kind":"branch","branch":"feat/login","path":"~/dev/uxd/my-project/trees/feat-login","ports":[3053],"created":true}
code
Materializes if needed, then opens the workspace in your editor.
uxd my-project 42 code
uxd my-project 42 code --editor vim
| Flag | Effect |
|---|---|
--editor <cmd> | Override the configured editor for this run |
--fetch | Re-fetch before opening |
--setup / --no-setup | Force or skip [setup] |
--json is not supported for code.
run <name>
Materializes, runs [setup], then the named command from [commands] inside
the worktree. Passthrough args are appended.
uxd my-project 42 run dev
uxd my-project 42 run test -- --watch
| Flag | Effect |
|---|---|
--no-setup | Skip [setup] |
--reseed | Re-copy seed files before running |
--fetch | Re-fetch before running |
--port <n> | Override the allocated port for this invocation |
--env K=V | Add or override one environment variable (repeatable) |
--dry-run prints the computed environment as export lines followed by the
shell-quoted command, and runs nothing.
exec -- <argv…>
Like run, but for an ad-hoc command spawned directly — no shell, so no
quoting surprises.
uxd my-project 42 exec -- pnpm test
uxd my-project 42 exec --no-setup -- git log --oneline -5
Accepts the same environment flags as run.
shell
An interactive shell inside the workspace with the full uxd environment
exported ($UXD_PORT, $UXD_PATH, $UXD_DATA_DIR, …).
uxd my-project 42 shell
uxd my-project - shell
sync
Re-fetches the ref and hard-resets the worktree to it.
uxd my-project 42 sync
| Flag | Effect on local changes |
|---|---|
| (none) | Refuses if the tree is dirty |
--stash | Stash them, then reset |
--discard | Discard them, then reset |
--fresh | Remove the worktree and re-materialize from scratch |
--stash, --discard and --fresh are mutually exclusive.See Refresh a workspace.
diff
For a PR workspace with gh available, renders gh pr diff against the real PR
base. Otherwise falls back to git diff <merge-base>...HEAD in the worktree.
uxd my-project 42 diff
uxd my-project 42 diff --stat
uxd my-project 42 diff --tool
uxd my-project 42 diff -- --color-words
| Flag | Effect |
|---|---|
--stat | Summary instead of full patch |
--tool | Use git difftool (always local, never gh) |
info
One workspace in detail.
uxd my-project feat/login info
slug: feat-login
kind: branch
ref: feat/login
branch: feat/login
path: ~/dev/uxd/my-project/trees/feat-login
ports: 3053
status: clean
created: 2026-07-25T05:51:38.363Z
last used: 2026-07-25T05:51:38.827Z
| Flag | Effect |
|---|---|
--du | Include on-disk size |
--json | Machine-readable object |
rm
Removes one workspace.
uxd my-project 42 rm
uxd my-project 42 rm --force --yes
| Flag | Effect |
|---|---|
--force | Remove even if the worktree is dirty (discards changes) |
--yes | Skip the confirmation prompt |
To remove several at once, use clean.