Top-Level Verbs

These verbs take no project argument.

setup

First-run onboarding. Creates the config dir if missing, ensures defaults.root so derived paths resolve, and scaffolds your first project file. It is the only command exempt from the config-dir existence check — it is what creates the dir.

uxd setup [--name <name>] [--repo <url>] [--root <dir>] [--default-branch <branch>] [--force]

On a terminal it prompts for each field in order. Every prompt is also a flag, so the same command runs non-interactively in CI.

--root is skipped once defaults.root is set. The project name must match ^[a-z0-9][a-z0-9._-]*$ and cannot be defaults or seeds.

Preview the writes without making them:

uxd setup \
  --config-dir ./ci-config \
  --name acme-web \
  --repo git@github.com:acme/acme-web.git \
  --default-branch main \
  --yes --dry-run

mkdir -p ./ci-config
write ./ci-config/defaults.toml
  root = "~/dev/uxd"
write ./ci-config/acme-web.toml
  repo = "git@github.com:acme/acme-web.git"
  default_branch = "main"

Guards:

• Invalid or reserved name, or an empty repo → E_USAGE, nothing written.
• Project file already exists → E_CONFIG unless you pass --force, which overwrites only that project file.
• A required value missing on a non-TTY with no flag → E_USAGE naming the flag.

The freshly written file is validated with the normal loader before success is reported, so a bad combination fails here rather than on your next command.

projects

uxd projects

NAME      REPO                              WORKSPACES  PATH-EXISTS
demo-app  git@github.com:acme/demo-app.git  1           yes

--json emits an array:

[{"name":"demo-app","repo":"git@github.com:acme/demo-app.git","workspaces":1,"pathExists":true}]

doctor

Diagnoses environment and configs. Exits non-zero if any check fails.

uxd doctor

OK   git version: git 2.50.1
OK   gh (github cli): authenticated
OK   config dir: ~/.uxd
OK   state dir: ~/.local/state/uxd
OK   project demo-app: config: schema-valid
OK   project demo-app: repo: bare repo at ~/dev/uxd/demo-app/repo
OK   project demo-app: fetch refspec: remote.origin.fetch configured

Checks: git version, gh presence and auth, config-dir readability, state-dir writability, stale locks, and per project — schema validity, the bare repo and its fetch refspec, editor binary on PATH, commands that shadow built-in verbs, core.hooksPath, and worktree/state drift.

See Troubleshooting for what to do with a WARN or FAIL.

config

uxd config path                 # print the config dir in use
uxd config edit [project]       # edit defaults.toml, or one project file
uxd config add [project]        # like edit; seeds a starter template if absent
uxd config validate [project]   # validate all configs, or one

uxd config path

~/.uxd

uxd config validate

→ all project configs valid

config path is the fastest way to confirm which directory is actually in use when UXD_CONFIG_DIR or --config-dir is in play. See Configuration overview.

completions

Prints a completion script for bash, zsh, or fish to stdout.

eval "$(uxd completions zsh)"

See Install shell completions.

help and version

uxd help       # the grammar, verbs, flags, and config-dir resolution order
uxd version    # the version string