Configuration
Overview
Where uxd looks for configuration, what lives in the config directory, and how defaults.toml relates to a project file.
uxd reads per-project TOML from one config directory. There is no
project-local config file — nothing is added to your repository.
Where the config directory is
--config-dir → $UXD_CONFIG_DIR → ~/.uxd
The first one set wins. uxd config path prints the winner:
uxd config path
~/.uxd
Layout
<config-dir>/
defaults.toml # optional global defaults
my-project.toml # one file per project; filename = project name
seeds/
my-project/ # seed file tree for project "my-project"
.env.local
Project names must match ^[a-z0-9][a-z0-9._-]*$. defaults and seeds are
reserved.
defaults.toml
Three optional keys, applied to every project that does not override them:
~/.uxd/defaults.toml
root = "~/dev/uxd" # base dir for derived repo_path / worktrees_path
editor = "zed" # fallback editor preset or template
default_command = "code" # fallback default verb
env and commands are not allowed in defaults.toml. Per-project config
stays self-contained on purpose — you should be able to read one file and know
what a project does.Creating and editing
uxd setup # scaffold the config dir and your first project
uxd config add my-project # create a project file from a starter template
uxd config edit my-project # open an existing one
uxd config edit # open defaults.toml
Validating
uxd config validate
→ all project configs valid
Validation is aggregate — one run reports every schema error in a file, not
just the first. Pass a project name to check one file. Invalid config exits 3
(E_CONFIG).