CLI | PixilUI docs

npx pixilui sets up an app for PixilUI, finds items by what they do, and installs them through the shadcn CLI with your package manager. It does not replace shadcn: it writes the registry entry, checks the names, handles the Pro key, runs shadcn add and then says what landed where.

Set up an app#

Run it once in a React 19 app with Tailwind v4:

bash

npx pixilui@latest init

init reads package.json to find Next.js or Vite, Tailwind and your package manager. It runs shadcn init when there is no components.json, adds the @pixilui registry without touching your other registries, and installs the foundation. It stops on Tailwind 3 and tells you why.

Then it writes the agent rules, so the agent in your editor follows them every session:

File	Read by
`AGENTS.md`	Codex, Claude Code, Copilot and most agents. `init` adds a PixilUI block and keeps the rest of the file.
`.cursor/rules/pixilui.mdc`	Cursor, on every request.

The rules: search the MCP server before building an approval, run, tool call or streaming UI by hand; read the item's page before its first use; tokens only, never hex or palette classes; one primary action per surface; restyle through className and data attributes; motion from motionTokens. Run init again after an update and both files are brought up to date in place. --no-rules skips them.

Add items#

bash

npx pixilui@latest add approval-card run-timeline

Every name is checked against the catalog first, so a typo gets suggestions instead of a failed download. add then runs shadcn@latest add through the package manager the project uses and prints one line per item with the path it went to. Items land in components/pixilui/, with the items they depend on and the foundation.

Package manager	Command
npm	`npx pixilui@latest add approval-card`
pnpm	`pnpm dlx pixilui@latest add approval-card`
yarn	`yarn dlx pixilui@latest add approval-card`
bun	`bunx --bun pixilui@latest add approval-card`

Every item page shows the command for the package manager you pick, for shadcn and for this CLI, and remembers the choice.

--dry-run prints what would run without running it. --overwrite replaces files you already have, and --yes answers the questions for you (for scripts).

Agent skill#

bash

npx pixilui@latest skill

Installs the PixilUI skill into .claude/skills/pixilui/ in the project, where Claude Code loads it: the workflow, the rules for tokens, motion, copy and accessibility, and every item by job. --global puts it in ~/.claude/skills/pixilui/ for every project. Running it again rewrites only the files that changed. AI and agents has what is in it.

Find items#

bash

npx pixilui@latest search "ask before the agent sends an email"
npx pixilui@latest list --category ai

search ranks by what an item is for, not only its name, with the same search the MCP server uses. Both take --tier free or --tier pro and --json. The catalog is cached for an hour and bundled into the CLI, so both work offline.

Pro#

bash

npx pixilui@latest login

The browser opens the PixilUI login and asks you to authorize the CLI on that computer. The CLI saves a key to ~/.config/pixilui/credentials.json, readable only by you, and inside a project also writes PIXILUI_TOKEN to .env.local and adds .env.local to .gitignore. components.json only ever holds the ${PIXILUI_TOKEN} reference, never the key.

After that, add installs Pro items like free ones. Without a Pro licence or Team seat the login page says so and no key is made.

CI and machines without a browser#

Create an access token on your account and pass it in:

bash

npx pixilui@latest login --key "$PIXILUI_TOKEN"

Or skip login and set PIXILUI_TOKEN in the environment. The CLI looks for the key in that order: the environment, the project's .env.local, then the key saved by login.

Update#

bash

npx pixilui@latest update

update finds the items already in components/pixilui/ and installs them again over your copies. It asks first; pass --yes when no one is there to answer.

What it sends#

add and init send one report per run: the item names, the CLI version, the framework and whether it ran in CI. No project names, paths, IDs or keys. Turn it off with PIXILUI_TELEMETRY=0 or DO_NOT_TRACK=1; the first run prints a notice that says so. The privacy policy has the details.

Options#

Option	Does
`--cwd <dir>`	Run in another folder
`--offline`	Use the bundled catalog, no network
`--help`, `--version`	What they say

Exit codes: 0 done, 1 failed, 2 wrong usage.