# 21st CLI

Search, retrieve, install **and publish** [21st.dev](https://21st.dev) components, themes and templates from your terminal, generate UI with 21st AI, and wire the 21st MCP into your editor. The CLI and the 21st MCP share one endpoint and one login, so every command returns exactly what an MCP client (Cursor, Claude, etc.) sees.

> **One unified CLI.** `@21st-dev/cli` (bin `21st`) is now the single tool for everything 21st. It supersedes the older `@21st-dev/registry` (publish/install) and `@21st-dev/magic` (Magic MCP) packages — use `21st` for all of it. Old `@21st-dev/magic` configs keep working: since 0.2.0 that package is a thin proxy to the same 21st MCP endpoint this CLI configures.

## Install

```bash
npm i -g @21st-dev/cli
# or run without installing:
npx @21st-dev/cli search "pricing table"
```

## Sign in

```bash
21st login      # opens your browser, saves a token locally (~/.config/21st)
21st whoami     # show the signed-in account
21st usage      # tier + remaining free daily quota
```

You can also authenticate with an API key from https://21st.dev/settings/api-keys via the `TWENTYFIRST_TOKEN` (or `API_KEY_21ST`) env var, or the `--api-key <key>` / `--token <key>` flag. A retired `an_…` key left in an env var is skipped so it can't shadow a working `21st login` session.

## Commands

| Command                                                                                                                                      | What it does                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `21st search <query> [--type component\|theme\|template] [--context auto\|path] [--tag] [--color] [--sort] [--json]`                          | Search metadata; Design Context adds confidence and fit rationales.                                                              |
| `21st logo <query> [--limit N] [--json]`                                                                                                     | Search brand + UI SVG logos. Free, no login required.                                                                            |
| `21st get <id> [--json]`                                                                                                                     | Print one component's code + demo by its search id (metered).                                                                    |
| `21st theme <id> [--json]`                                                                                                                   | Print one theme's CSS by its search id — free.                                                                                   |
| `21st add <user>/<slug> [--print]`                                                                                                           | Install a component via the 21st shadcn registry.                                                                                |
| `21st bookmarks [--type ...] [--limit N]` / `21st bookmark <id> --type <kind> [--remove]`                                                    | List / add / remove a bookmark ("heart") across any entity.                                                                      |
| `21st lists` / `21st list <listId>` / `21st list-new <name>` / `21st list-add <listId> <id> --type <kind> [--remove]`                        | Manage named bookmark lists.                                                                                                     |
| `21st teams` / `21st team <teamId>` / `21st team-lists <teamId>` / `21st team-components <teamId> [--library <id>]`                          | Browse your teams' shared libraries + lists.                                                                                     |
| `21st components [--status all\|draft\|published\|private] [--scope all\|personal\|team:<uuid>] [--json]`                                    | List every accessible personal/Team component and owned draft, using stable refs.                                                |
| `21st open <component:<id>\|draft:<uuid>> [--no-open]`                                                                                       | Resume a draft or create/resume a reviewed revision of an existing component; `--no-open` prints its URL.                        |
| `21st publish <Component.tsx> [--component component:<id>] --description "…" [--to <library-slug>] [--preview <image>] [--no-open]`          | Create a draft, open CLI Review with live demos and automatic media, then publish a new component or an explicit owned revision. |
| `21st submit <slug>` / `withdraw` / `resubmit` / `remove-from-catalog`                                                                       | Manage catalog review separately from Published/Private access.                                                                  |
| `21st publish-theme <theme.css> --name "…" [--tags a,b]`                                                                                     | Publish a theme (CSS with `:root` + `.dark`).                                                                                    |
| `21st publish-template <name> --site <url> --preview <img-url> [--price N]`                                                                  | Submit a template listing for review.                                                                                            |
| `21st publish-gradient <recipe.json> --name "…" --thumbnail <image>`                                                                         | Publish a Gradient Builder recipe to the API key's scope.                                                                        |
| `21st publish-ascii <recipe.json> --name "…" --thumbnail <image> [--video <file>] [--mask <file>] [--private]`                               | Publish an ASCII recipe to the API key's scope.                                                                                  |
| `21st edit component:<id> --type component [...]` / `21st delete component:<id> --type component --yes`                                      | Edit or unpublish the exact component returned by inventory, including manageable team components.                               |
| `21st edit <id> --type <theme\|template> [...]` / `21st delete <id> --type <theme\|template> --yes`                                          | Edit or remove a theme/template using its existing API-key-scoped id semantics.                                                  |
| `21st delete draft:<uuid> --type draft --yes`                                                                                                | Permanently delete an owned draft and its unpublished sandbox.                                                                   |
| `21st publish <file> --prepare [--wait-video] [--media-dir <dir>]` / `21st publish <file> --draft draft:<uuid> --auto [--wait-video]`        | Headless flow: prepare revision-bound media without publishing, then publish that exact draft entirely from the CLI.             |
| `21st profile get [--json]` / `21st profile set --file <path.json> [--clear]` / `21st profile upload <image>`                                | Read, replace, or clear your bento profile board and upload media for it (requires a `21st_sk_…` API key).                       |
| `21st inspiration-feedback <feedbackId> --outcome accepted\|rejected`                                                                        | Record a privacy-safe inspiration decision.                                                                                      |
| `21st generate "<prompt>" [--context auto\|path] [--variants N]`                                                                             | Generate grounded alternatives and open their preview.                                                                           |
| `21st generation <projectId>` / `21st iterate <projectId> "<change>" [--take N]` / `21st take <projectId> [--take N] [--code] [--select]`    | List a sketch generation's takes, refine one, and grab its code (`generation`/`take` are free).                                  |
| `21st init --design-context [--check\|--refresh]`                                                                                            | Create or verify `.21st/design.json` and `.21st/DESIGN.md`.                                                                      |
| `21st review <path...> [--fix] [--json]`                                                                                                     | Run deterministic local UI review and conservative fixes.                                                                        |
| `21st skills install\|list\|check\|update\|remove`                                                                                           | Manage verified skills for Claude, Cursor, and Codex.                                                                            |
| `21st skills catalog`                                                                                                                        | Inspect curated compatibility; broad discovery stays on skills.sh.                                                               |
| `21st install-skill`                                                                                                                         | Compatibility alias for `21st skills install --global`.                                                                          |
| `21st init --client <name> [--write]`                                                                                                        | Print or write the 21st MCP config for an editor.                                                                                |
| `21st login` / `logout` / `whoami` / `usage`                                                                                                 | Manage your local session and see quota.                                                                                         |

For a new component slug, `publish` opens the dedicated CLI Review and waits for its final Publish action. The review shows the live selected demo and the total demo count. It starts a required cover first and attempts an optional best-effort video in the background; publishing remains locked until every demo has a valid cover, but does not wait for video. A video is accepted only when a required interaction produces a visible result, so interactive controls should expose stable semantic selectors such as an `id`, native role, or `data-slot`. A ready video is included, and generated media can always be replaced manually. The CLI also rejects non-portable theme expressions such as `oklch(var(--primary))`; use `bg-primary` or `var(--color-primary)`. `--preview` stages an initial cover but does not bypass confirmation, and `--no-open` prints the review URL without launching it. The current CLI command seeds one self-contained component and one demo; the review itself supports multiple demos. In CI the command prints the structured draft result and exits with code `2` instead of waiting. Both a `21st login` session and a real API key (`21st_sk_…` from https://21st.dev/settings/api-keys) are accepted for component publishing and component metadata management. Theme/template management keeps its existing API-key semantics.

`21st components` drains both independent server cursors before printing, so the default `--status all --scope all` output contains every accessible personal or Team component and every owned draft rather than a first-page sample. `21st open draft:<uuid>` resumes that draft. `21st open component:<id>` creates or resumes a server-owned CLI Review revision from the retained published component code and demos; the live component stays unchanged until the revision is published. The revision requires fresh covers, while optional video generation runs best-effort in the background. `--no-open` creates or resumes the workspace and prints its URL without launching a browser.

Only the original component author can check out a code revision. A Team manager can still edit or unpublish a teammate's component metadata by its stable `component:<id>` ref. If retained source, dependencies, style, support files, or the default demo cannot be reproduced safely, checkout fails closed; use `21st publish <file> --component component:<id>` with a local source file instead. Proof-backed legacy CLI drafts are recovered into inventory for their authenticated scope; an older unsigned draft whose scope cannot be proven may need to be recreated. Inventory, component checkout, and component metadata edit/delete accept the saved `21st login` session or an API key. Theme/template management keeps its API-key requirement.

`--client` accepts `cursor`, `claude`, `codex`, `vscode`, or `windsurf`. With `--write`, the config is **merged** into your existing MCP config (it won't clobber other servers).

## How it works

Search and all metadata/list commands are free; retrieving a component's code (`21st get`, or the MCP `get_component` tool) is the metered action — themes are free to retrieve too. Signed-in free accounts get a small daily component-code allowance, then an upgrade prompt; members get unlimited retrieval. Private/team components are gated by team membership instead, never metered.

## Docs

Full guides live at **[help.21st.dev/cli](https://help.21st.dev/cli)** — [publishing](https://help.21st.dev/cli/publish) (every flag, exit code and failure mode), [finding and installing](https://help.21st.dev/cli/find), [21st AI](https://help.21st.dev/cli/generate), [project-aware design](https://help.21st.dev/cli/design-runtime), and the [command reference](https://help.21st.dev/cli/reference).

## License

MIT © 21st.dev