CLI Reference
Project Verbs
Reference for list and clean — the verbs that take a project but no ref.
These verbs take a project and no ref:
uxd <project> <verb> [flags]
list
The project's workspaces. list is what a bare uxd <project> falls back to
when there is no TTY.
uxd my-project list
SLUG KIND BRANCH STATUS PORT AGE LAST USED
feat-login branch feat/login clean 3053 1m 0m
| Column | Meaning |
|---|---|
SLUG | The workspace identifier — what clean and the workspace verbs accept |
KIND | branch, pr, commit, or path (adopted) |
BRANCH | The checked-out branch, when there is one |
STATUS | clean, dirty, missing — or, for PRs, the PR state plus a CI mark |
PORT | The first allocated port |
AGE | Time since the workspace was created |
LAST USED | Time since a uxd command last touched it |
| Flag | Effect |
|---|---|
--du | Add a disk-usage column |
--json | Machine-readable array — deterministic and offline (no gh refresh) |
uxd my-project list --json
[{"slug":"feat-login","ref":"feat/login","kind":"branch","branch":"feat/login","path":"~/dev/uxd/my-project/trees/feat-login","adopted":false,"ports":[3053],"createdAt":"2026-07-25T06:00:28.086Z","lastUsedAt":"2026-07-25T06:00:28.148Z","dirty":false,"missing":false}]
For PR workspaces,
STATUS shows the PR state plus a CI mark (✓ pass,
✗ fail), refreshed from gh stale-while-revalidate and bounded to about two
seconds. The table always renders, even when gh is slow or absent.With no workspaces:
→ no workspaces for 'my-project'
clean
Removes workspaces by explicit slug or by filter. Explicit slugs and filters cannot be combined.
uxd my-project clean feat-login
uxd my-project clean --all
| Filter | Removes |
|---|---|
--all | Every workspace for the project |
--merged | Branches merged into the default branch (git-only check) |
--closed | Workspaces whose PR is closed or merged (prefers gh) |
--older-than <dur> | Workspaces idle for at least <dur> (s/m/h/d/w) |
Filters intersect: --merged --older-than 7d removes only workspaces that
are both.
| Flag | Effect |
|---|---|
--force | Remove dirty worktrees too (discards changes) |
--include-adopted | Include workspaces adopted from a path |
--prune-state | Drop state entries whose worktree is gone |
--yes | Skip the confirmation prompt |
--dry-run | Print the plan and stop |
clean always prints a plan first:
→ plan:
feat-login (clean, 16 KB)
and then, once approved, the removed slugs and the space reclaimed:
feat-login
→ freed 16 KB
Dirty worktrees are skipped with a warning rather than removed:
warning: skipping feat-login: worktree is dirty (use --force)
Without confirmation on a non-interactive terminal:
error(E_USAGE): refusing to remove 1 workspace(s) without confirmation
hint: pass --yes for non-interactive use
See Clean up workspaces for the full workflow.