21st CLI

Search, retrieve, install and publish 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

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

Sign in

21st login      # opens your browser, saves a token locally (~/.config/21st)
21st whoami     # show the signed-in account
21st usage      # retrieval tier/quota + hosted AI access
21st usage --json # structured account capabilities, including aiGenerationEnabled

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

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 devin (Devin Desktop, formerly Windsurf; windsurf is still accepted as an alias). 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.

Hosted 21st AI is a separate capability: Builder component access alone does not enable generate or iterate. Check 21st usage --json before generating; only aiGenerationEnabled: true confirms AI access, and this field does not report the remaining AI credit balance. With AI off, use 21st search and 21st get, then adapt the returned code with your own coding agent. Existing generations remain readable through 21st generation and 21st take.

The MCP hides generate and iterate_generation when AI access is off. Cached calls and direct CLI commands return ai_subscription_required with guidance to use search and component retrieval; do not retry generation until AI access is enabled. Refresh the MCP tool list or reconnect after enabling AI. generate --json and iterate --json preserve the denial reason and exit nonzero.

1.17.1

• 21st usage --json now returns the MCP's structured account capabilities, including hosted AI access when the server reports it.
• Clarified the separate requirements for component retrieval and hosted AI, including the workflow for using your own coding agent with AI off.

Docs

Full guides live at help.21st.dev/cli — publishing (every flag, exit code and failure mode), finding and installing, 21st AI, project-aware design, and the command reference.

License

MIT © 21st.dev