CLI

uix-ui puts your design system in a React and Tailwind v4 project. It has no dependencies and runs with npx.

Requirements

Node 18 or newer
React 18 or 19
Tailwind CSS v4. The CLI stops if it finds v3.

You don’t install anything first. Run it with npx uix-ui@latest, and use npx uix-ui for later commands in the same project. pull and sync need no API key.

Commands

Command	What it does
`new <folder> <id>`	Makes a Vite, React and Tailwind v4 app in a new folder that already uses your system.
`new <folder> --theme <preset>`	The same app, started from a free preset. No account or id needed.
`pull <id> [components…]`	Writes your system’s theme, tokens and any components you name into this project.
`sync`	Pulls again after you change the system. Reads the id from `uix.json`.
`init [--preset <id>]`	Sets up a uix-ui theme, the `cn()` helper and `components.json`.
`add <component…>`	Copies components into your project, with what they depend on.
`theme <preset>`	Switches to another uix-ui theme. Components don’t change. Add `--css` to write just `uix/theme.css`, in any folder.
`list`	Lists every component and theme in the registry.
`help`	Prints the four ways to use your system and the commands.

new

Makes a new app from your saved system. The folder must be new or empty.

Terminal

npx uix-ui@latest new my-app <id>

It creates a Vite app with the React and TypeScript template, installs packages, adds tailwindcss and @tailwindcss/vite, wires Tailwind into vite.config and src/index.css, pulls your system with the Button and Card components, and writes a sample src/App.tsx. Then:

Terminal

cd my-app
npm run dev

No saved system yet? Start from a free preset instead. Use --theme and the preset’s name, with no id:

Terminal

npx uix-ui@latest new my-app --theme terracotta-drafting

Give it an id or --theme, not both.

pull

What happens

you

terminal

$ npx uix-ui pull <id>
src/styles/uix.css
components.json
uix.json

Synced

Run it in your project folder. Name components after the id to add them too.

Terminal

npx uix-ui@latest pull <id> button card

In an app (a folder with package.json), it sets up components.json with your system’s registry, writes the theme to src/styles/uix.css, writes your token files to src/styles/tokens/, adds the cn() helper and the components, and installs their packages.

In a folder without package.json, it writes plain files instead: uix/uix.css, your token files in uix/, and any components you named. Link uix/uix.css from any page.

Either way it saves uix.json, so sync knows what to update:

uix.json

{
  "system": "<id>",
  "name": "Teal Design System",
  "version": 3
}

sync

Run it after you save changes in Studio. It checks the version first and only pulls when it moved.

Terminal

npx uix-ui sync

When nothing changed it prints Up to date: "<name>", version <n>. and stops.

init, add, theme and list

These come from uix-ui, the open-source React library that shares the CLI. After pull, add reads your system’s registry, so new components come in your colors.

Terminal

# set up a uix-ui theme instead of a saved system
npx uix-ui@latest init --preset lagoon-stretch
# copy more components
npx uix-ui@latest add input select
# switch theme; components don't change
npx uix-ui@latest theme <preset>
# every component and theme
npx uix-ui@latest list

Leave out --preset to start with the UIX default theme. Browse all 42 themes at /ui/themes.

Options

Option	What it does
`--overwrite`	Replaces files you already have. Without it, existing files are kept and listed as skipped.
`--no-install`	Prints the install command instead of running it.
`--preset <id>`	With `init`: the uix-ui theme to start from.
`--theme <preset>`	With `new`: start from a free preset instead of a saved system.
`--css`	With `theme`: write only `uix/theme.css`, in any folder.

Files it changes

File	What happens
`components.json`	Created, or the `@uix` registry is added to yours
`src/styles/uix.css`	The theme: colors for light and dark, type scale, spacing, radius, shadows
Your main CSS file	`@import "./styles/uix.css";` is added after `@import "tailwindcss";`
`src/styles/tokens/`	Your W3C token files (`pull` only)
`src/lib/utils.ts`	The `cn()` helper, if you don’t have one
`src/components/ui/`	The components you add
`index.html`	Google Fonts links for the theme (Vite)
`package.json`	`clsx`, `tailwind-merge` and the components’ packages, if missing
`uix.json`	Your system’s id, name and version (`pull` only)

It finds your main CSS file at src/index.css, src/app/globals.css, app/globals.css, src/styles/global.css (Astro) or app/app.css (React Router), among others. Without a src folder, files go in the project root.

Packages: it uses pnpm, yarn or bun when it finds their lock file, and npm otherwise.
Fonts: in a Vite app it puts the font links in index.html, between  markers, and replaces them on the next run. Next.js and others get the links printed to add yourself.

UIX Pro items

Marketing blocks such as hero and pricing-card, the visual styles and the Pro themes need your UIX Pro key. Set UIX_LICENSE in your environment, or in .env or .env.local in the project folder.

Terminal

export UIX_LICENSE=<your key>
npx uix-ui@latest add hero pricing-card
# visual styles, then <html data-skin="glass">
npx uix-ui@latest add skins
# list shows the Pro items too
npx uix-ui@latest list

Troubleshooting

Message	What to do
`UIX themes need Tailwind CSS v4 (found v3).`	Upgrade Tailwind to v4 first.
`run this in your app folder (no package.json here).`	`init` needs a project. `cd` into it.
no components.json here. Run `npx uix-ui init` first.	`add`, `theme` and `list` need setup. Run `pull <id>` or `init`.
`No design system with id "…"`	Check the id on your Use it page or in Account.
`nothing to sync yet.`	Run `npx uix-ui pull <id>` once in this folder.
`"my-app" is not empty.`	Pick a new folder name for `new`, or run `pull` inside that folder.
`skipped … (exists, use --overwrite)`	Your file differs from the new one. Add `--overwrite` to replace it.
`"…" is part of UIX Pro. Set UIX_LICENSE to your key`	Set `UIX_LICENSE`, or leave that item out.