Commands

Every command accepts --help. Pass --no-color or set the NO_COLOR environment variable to disable color output. Colors are also disabled automatically when stdout is not a terminal, unless FORCE_COLOR=1 is set.

`xds list`

Lists the available client stacks and color themes.

$ xds list
Targets
  web-react            Web                             React 19, Vite, Tailwind v4, HeroUI v3
  desktop-gpui         Desktop (macOS)                 Rust, GPUI, GPUI Component
  mobile-react-native  Mobile (iOS, Android)           React Native, Expo
  kotlin-compose       Kotlin (Android, iOS, Desktop)  Kotlin, Compose Multiplatform

Themes
  forest  A deep green accent on sage neutrals.
  indigo  The default. An indigo accent on cool grey neutrals. (default)
  ocean   A clear blue accent on slate neutrals.
  plum    A magenta accent on mauve neutrals.
  sunset  A burnt orange accent on warm stone neutrals.

`xds create <directory>`

xds create <directory> [--name <name>] [--title <title>] [--targets <a,b|all>]
                       [--theme <theme>] [--yes] [--dry-run] [--force]

When run interactively in a terminal, xds create my-app prompts for any options not supplied via flags:

The project name (text input, defaulting to the target directory name).
The client targets to include (multi-select list: Up and Down or k and j to move, Space to toggle, a to toggle all, Enter to confirm).
The color theme (select list with a live preview rendered below it; see Themes).

Pressing Esc or Ctrl-C cancels the prompt at any point. No files are written until the final prompt is confirmed.

When all options are supplied via flags, xds runs without prompting:

$ xds create orbit --name orbit --targets web-react,desktop-gpui --theme ocean
Created Orbit in orbit
  name     orbit
  targets  web-react, desktop-gpui
  theme    ocean
  files    85

Regenerated the token files for the ocean theme.

Next steps
  cd orbit
  mise trust
  mise install
  mise run fmt  once: the new name changes line lengths and import order
  mise run check

Run
  mise run //web:dev      Start the web app on http://localhost:5173
  mise run //desktop:dev  Start the desktop app

Flag	Meaning
`--name`	Lowercase ASCII letters and digits, starting with a letter, up to 40 characters. Replaces `acme` across the project: crate names (`orbit-ui`), the npm scope (`@orbit/ui`), CSS custom properties (`--orbit-color-*`), and the Kotlin package (`orbit.tokens`). Kotlin and Java reserved keywords are rejected
`--title`	Display name used to replace `Acme`. Accepts letters, digits, spaces, and `-`, `_`, `.`. Defaults to the project name with an uppercase first letter
`--targets`	Comma-separated target IDs, or `all`
`--theme`	Theme name. Defaults to `indigo`
`--yes`, `-y`	Skip interactive prompts and use defaults for any omitted flags: the project name comes from the directory name, all targets are included, and the theme defaults to `indigo`
`--dry-run`	Print the file paths that would be written without writing anything to disk
`--force`	Allow scaffolding into a non-empty directory. Existing files at matching paths are overwritten, while unrelated files are left untouched

When stdout is not a terminal (for example, in a script or CI job), there is no way to prompt interactively. In that case, --name and --targets are required unless --yes is passed, and the error message lists any missing flags.

What a scaffolded project contains:

The files for the selected targets along with shared project files: design/, tools/design-build/, mise.toml, the CI workflow, and docs/design-system.md. Selecting any JavaScript target also includes the pnpm workspace configuration and packages/tokens. Selecting the desktop target includes the Cargo workspace configuration.
Only the generated token files consumed by the selected targets. design/build.json is filtered to those outputs so mise run tokens does not generate files for unused stacks.
Root configuration files trimmed to match the selection: mise.toml includes only the relevant tools and tasks, and the CI workflow includes only the relevant jobs.
A project README.md with the run commands for the selected stacks.
.xds.json, which records the xds version, project name, title, targets, and theme for use by xds add and xds theme.

Files specific to maintaining this template repository are excluded: this repository’s own README, license, contributing guide, the CLI itself, and lockfiles. Because a scaffolded project contains a custom subset of workspace packages, it needs its own lockfiles; running mise run check for the first time resolves dependencies and generates them.

Run mise run fmt once before running mise run check for the first time. The template source is formatted for the placeholder name acme; substituting a different project name can push lines past the formatter’s line-length limit or change alphabetical import ordering (such as orbit_tokens), causing the formatting check in mise run check to fail until the formatter has been run. Projects that only include the Kotlin stack do not have a fmt task and can skip this step.

When --title contains spaces, Acme inside code identifiers is replaced with the space-stripped title: --title "Orbit Notes" turns AcmeTheme into OrbitNotesTheme while turning <title>Acme</title> into <title>Orbit Notes</title>.

`xds add <target>...`

Adds one or more client stacks to an existing project created with xds create. Run it from the project root, or pass --project <dir>.

$ xds add kotlin-compose
Added kotlin-compose to Orbit
  59 new files
  updated: .gitattributes, .github/workflows/ci.yml, README.md, design/build.json, mise.toml

Regenerated the token files from the project's tokens.

Next steps
  mise trust
  mise install
  mise run check

Run
  mise run //kotlin:desktop  Start the Compose desktop app
  mise run //kotlin:android  Run the Compose app on Android

add compares the initial project state recorded in .xds.json against the template output with the new targets included, and applies the difference:

Files belonging exclusively to the new targets are written to disk.
Shared files affected by the new targets (such as mise.toml or the CI workflow) are updated in place if the project’s copy still matches what xds originally wrote byte for byte.
If a shared file has been modified locally, xds leaves it untouched, writes the updated version alongside it as <file>.xds-new, and lists the path under “Needs a manual merge”. Reconcile the changes manually and delete the .xds-new file.
design/build.json is merged at the JSON level rather than overwritten: any existing output paths you customized are preserved, and the new target’s outputs are appended.
Files unaffected by the new targets are never modified.
.xds.json is updated with the new target list.

Because the template embeds generated token files for the default theme, add runs the token generator after writing the new files so that the newly added stack matches the project’s current tokens and theme. If Node is not available, it notes this, and mise run tokens can be used to regenerate them later.

--dry-run reports the same comparison and writes nothing.

If a project was created with an older version of xds, shared files may differ from what the current version writes even without local edits. In that case, add flags those files for manual merge and notes which version originally created the project.

`xds themes [name]`

Renders a terminal preview of all available themes, or of a single named theme. See Themes.

`xds theme [name]`

Applies a color theme to an existing project. Run it from the project root, or pass --project <dir>.

$ xds theme sunset
Applied the sunset theme and regenerated the token files.

When run in a terminal without a theme name, it opens the same interactive selector and live preview used by create, preselecting the project’s active theme.

--dry-run says whether the theme would change anything and writes nothing.

theme loads theme definitions and token files from the project directory rather than the embedded binary assets. Any custom themes added to design/themes appear in the selector, and the preview reflects any local edits to the project’s semantic color tokens. The command works in any directory containing design/tokens/palette.json and design/themes, including a checkout of this template repository.

`xds tokens [query]`

Lists the design tokens and their resolved values: per color mode for colors, and per input device for sizes.

xds tokens                      # every token
xds tokens button.primary       # tokens whose path contains this
xds tokens --tier semantic      # palette, semantic, component, or base

color.button.primary.background  light #4f46e5 (color.accent.default)   dark #5b5ef0 (color.accent.default)

Aliases are resolved to their final values, with the referenced token shown in parentheses. With --json, each token entry includes path, type, tier, description, values, and aliases.

When run inside a project or a checkout of this repository, tokens reads the local files in design/tokens. Elsewhere, it reads the template embedded in the binary, or you can pass --project <dir> to point to a project directory explicitly. components and contrast work the same way; in JSON output, the source field indicates project or template.

`xds components [name]`

Lists all components and the clients that implement them, or shows the details of a single component.

xds components                              # all of them
xds components Button                       # options, states, tokens, and the source file per client
xds components Button --client web-react    # one client only
xds components Button --code                # with the source code

This information comes from design/components.json, the component contract, which records each component’s purpose, options, states, accessibility notes, and the source file and symbol that implement it on each client. In a project created with xds create, the contract is filtered down to that project’s clients.

`xds contrast <foreground> <background>`

Computes the WCAG 2 contrast ratio between two colors. Each argument can be a hex color or a color token path (the leading color. prefix is optional).

xds contrast text.secondary background.surface
xds contrast '#84848f' '#ffffff' --min 4.5

color.text.secondary on color.background.surface
  light #5c5c66  #ffffff  6.60:1   text 4.5 pass   large text and UI 3 pass   AAA text 7 fail

Color tokens are evaluated in both light and dark modes. With --min <ratio>, the command exits with code 1 if either mode falls below the threshold. Translucent tokens are rejected; composite the color over its background first and pass the resulting hex value.

`xds doctor`

Runs a set of health checks on a project and reports each one as ok, warning, failed, or skipped:

Check	What it verifies
`record`	`.xds.json` is valid and references known targets
`tokens`	All token files parse cleanly and every alias resolves
`theme`	The palette matches one of the themes in `design/themes`, and it matches the theme named in the project record
`components`	Every component source file listed in `design/components.json` exists on disk
`node`	A Node version capable of running the token generator is available on `PATH`
`generated`	The generated platform token files are up to date with the token sources

The command exits with code 1 if any check fails. Warnings do not affect the exit code.

`xds mcp`

Starts a Model Context Protocol server communicating over stdin and stdout. See For scripts and agents.