---
title: CLI
description: "madeui init, add, diff, and list."
sidebar:
  order: 4
---

The `madeui` CLI sets up the StyleX build and copies components into your
project.

## init

```bash
npx @madeui/cli init
```

Sets up the current app:

- Detects the framework (Next.js or Vite) and wires the StyleX build —
  Babel + PostCSS plugin on Next.js, `@stylexjs/unplugin` on Vite. Config
  files it doesn't fully understand are never rewritten; it prints the exact
  snippet to apply instead.
- Offers to remove Tailwind when the app was scaffolded with it (the
  `--tailwind` option of `create-next-app`, or `@tailwindcss/vite`). madeui
  styles with StyleX, and running both means two CSS pipelines and a PostCSS
  config `init` can't own. Removal uninstalls the Tailwind packages, deletes
  or edits the PostCSS / Vite plugin wiring and any `tailwind.config.*`, and
  strips Tailwind at-rules (`@import "tailwindcss"`, `@theme`, `@plugin`,
  `@custom-variant`, …) from your stylesheets. Utility classes already in
  your JSX are left for you to restyle with StyleX.
- Installs `@stylexjs/stylex` and `@base-ui/react`.
- Ensures the global CSS has the `@stylex` marker with a `base` layer
  declared before it (unlayered CSS would outrank StyleX), and adds a browser
  reset in that layer when the file has none. The reset has the same coverage
  as Tailwind Preflight, so an app that drops Tailwind keeps its baseline; a
  Vite template never had one. See the
  [manual setup](/docs/installation#nextjs-manual) for details.
- Copies the design tokens (`lib/tokens.stylex.ts`, `lib/constants.stylex.ts`,
  `lib/themes.ts`) and utilities (`lib/stylex-utils.ts`).
- Applies the page styles from `lib/themes.ts`: `colorScheme` on `<html>`
  (light and dark mode) and `page` on `<body>` (background and text color).
  On Next.js it edits the root layout (`app/layout.tsx`), appending to an
  existing string or template-literal `className`; on Vite it adds the
  classes from the entry (`src/main.tsx`). A layout it can't read is left
  alone and the snippet is printed instead. See
  [page styles](/docs/installation#page-styles).
- Appends a component-conventions section to `AGENTS.md` so coding agents
  follow the house rules (tokens over literals, variants over escapes,
  `[data-*]` condition keys for Base UI state, reading `diff` before
  overwriting), and makes sure `CLAUDE.md`
  imports it (`@AGENTS.md`) so Claude Code reads it as well.
- Writes `madeui.json` with your paths and registry.

| Option | Description |
| --- | --- |
| `--registry <url\|dir>` | Registry to use (hosted URL or a local directory). |
| `--remove-tailwind` | Strip Tailwind without asking (for scripts and agents; without a TTY `init` keeps Tailwind). |
| `--keep-tailwind` | Leave Tailwind in place without asking. `init` then adds `@stylex` after the Tailwind import and prints the PostCSS entry to merge by hand. |
| `--no-install` | Print dependency installs (and uninstalls) instead of running them. |

## add

```bash
npx @madeui/cli add button dialog select
```

Copies components into `components/ui/`, resolving registry dependencies
(e.g. `pagination` pulls in `button`; every component pulls the tokens) and
installing missing npm packages.

| Option | Description |
| --- | --- |
| `--diff` | Show what would change without writing anything. |
| `--overwrite` | Replace files of the named components that have local changes, without asking. |
| `--registry <url\|dir>` | Registry to use. |
| `--no-install` | Print dependency installs instead of running them. |

Because you own the files, `add` never silently overwrites local edits — it
asks (or use `--diff` first). `--overwrite` covers only the components you
name: `add button --overwrite` leaves a rethemed `lib/tokens.stylex.ts`
alone. Name `theme` as well to replace it.

## diff

```bash
npx @madeui/cli diff
npx @madeui/cli diff button dialog
```

Compares the components installed in your project with the registry's
current version. Without arguments it lists every installed item; with
names it also prints the patch for each file, from your copy to the
registry's.

Each file is one of:

| Status | Meaning |
| --- | --- |
| `same` | Matches the registry. |
| `differs` | Differs from the registry. |
| `missing` | Part of an installed item, but not on disk. |

An item counts as installed when any of its files is at its path. A named
item that isn't installed is reported as `not-installed`.

`diff` has no record of what you installed, so `differs` can mean your edit,
a registry update, or both — read the patch before replacing the file. Each
item that differs comes with the command that brings it back to the
registry's version (`add <name> --overwrite`, or a plain `add` when files
are only missing).

| Option | Description |
| --- | --- |
| `--json` | Print a machine-readable report, patches included. |
| `--exit-code` | Exit with `1` when any installed item differs (for CI and agents). |
| `--registry <url\|dir>` | Registry to use. |

The `--json` report:

```json
{
  "registry": "https://madeui.com/r",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "status": "differs",
      "files": [
        {
          "path": "components/ui/button.tsx",
          "status": "differs",
          "patch": "--- components/ui/button.tsx\n+++ components/ui/button.tsx\n@@ …"
        }
      ],
      "fix": "npx @madeui/cli add button --overwrite"
    }
  ]
}
```

## list

```bash
npx @madeui/cli list
```

Lists every item in the configured registry with its description.