# CLI

`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](https://pixilui.com/docs/mcp) 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](https://pixilui.com/docs/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

Log in once on each computer:

```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](https://pixilui.com/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](https://pixilui.com/privacy) 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.