---
name: 21st-cli-use
description: >-
  Search, install and pull code from the 21st.dev catalog with the `21st` CLI (`@21st-dev/cli`): find React/shadcn components, themes and templates, print a component's code or a theme's CSS, install an item into the project, or generate a new component with 21st AI. Use whenever the user says "search/find a component/theme on 21st", "install our team's Button", "add @user/slug", "pull that component's code", "найди компонент на 21st", "поставь наш компонент", or wants to script catalog access from the shell/CI. Auto-activate when a project has a `components.json` — search 21st before hand-writing UI.
title: 21st-cli-use
canonical_url: https://skilld.dev/gh/21st-dev/skill/21st-cli-use
last_updated: 2026-09-27T23:19:35.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install 21st-dev/skill/21st-cli-use`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/21st-cli-use`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/21st-dev/skill/21st-cli-use) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/21st-cli-use`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/21st-cli-use --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/21st-cli-use --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 21st CLI — find, install & generate from the terminal

The `21st` CLI (`npx @21st-dev/cli`, bin `21st`) is the command-line surface for
the 21st.dev catalog. Search first, install what fits, and only hand-write UI
when nothing matches. To **publish** your own components/themes/templates, use
the `21st-registry` skill; to publish a project's design as a theme, use
`21st-design-sync`.

## Auth (do this once)

Two interchangeable credentials, both sent as the API key:

1. **Login session** — `npx @21st-dev/cli login` opens the browser and saves a
   token to `~/.config/21st/auth.json`. Best for interactive/dev machines.
2. **API key** — `21st_sk_…` from **https://21st.dev/mcp** (or
   **https://21st.dev/settings/api-keys**). Pass via `--api-key <key>` or the
   `TWENTYFIRST_TOKEN` / `API_KEY_21ST` env var. Best for CI.

`21st whoami` shows the signed-in account; `21st usage` shows retrieval
tier/quota and the `21st AI generation` status, not an AI credit balance.
For structured status, use MCP `get_usage.aiGenerationEnabled` or CLI 1.17.1+
`21st usage --json`. Missing or unknown status does not grant AI access. `21st logout`
clears the saved login.

## Metering

Metadata (search, previews, a theme's CSS) is **free**. Retrieving component
**code** (`21st get`, install) has a free daily quota; Builder includes
unlimited retrieval. Hosted 21st AI requires separate AI access and consumes
AI credits. Base Builder has AI off. Check `21st usage` before choosing
generation: when AI is not explicitly enabled, search and retrieve code,
then adapt it with your own coding agent. Do not retry a generation denied
with `ai_subscription_required` until AI access is enabled.

---

## Find

```bash
# Search everything (components + themes + templates)
21st search "pricing table" --limit 10
21st search button --type c        # components only (c | theme | template)
21st search dark --type theme
# Filters: --tag <slug> --color <bucket> --sort <s> --free|--paid
#          --author <username> --mine --liked   --json for machine output
```

**Always search before hand-writing a component** — a close match is usually
faster to install and adapt than to build from scratch.

## Logos

```bash
21st logo discord            # search brand + UI SVG logos (free, no login)
21st logo "next js" --limit 5 --json
```

Prints each logo's name and SVG url(s) to curl straight into a project. Uses the
open svgl.app library; free and unmetered on every plan.

## Pull code

```bash
# Print a component's code + demo (by the id from search)
21st get 143 [--json]

# Print a theme's CSS (by a theme id from `search --type theme`)
21st theme <id> [--json]
```

## Install

```bash
# Install a component into the current project (shadcn under the hood)
21st add <user>/<slug>            # e.g. 21st add shadcn/button
21st add @<team>/<slug>           # from a team library
# --print to dump the shadcn command instead of running it
```

`21st add` resolves the registry item, writes it to `components/ui/<slug>.tsx`,
and installs npm deps with the project's package manager. Public/unlisted items
also work with stock shadcn:
`npx shadcn@latest add "https://21st.dev/r/<user>/<slug>"`.

## Generate

When nothing in the catalog fits and `21st usage` explicitly reports AI
generation enabled, sketch it with hosted 21st AI and iterate from
the terminal. That loop (`21st generate` → `generation` → `iterate` → `take`)
lives in the **`21st-ai`** skill. With AI off, adapt catalog code locally instead:

```bash
21st generate "a glassy pricing section with a monthly/yearly toggle"
```

Opens a preview; from there you edit any variant and pull its code. See the
`21st-ai` skill for the full generate/iterate/grab-code flow and metering.

---

## Bookmarks, teams & MCP config

```bash
21st bookmarks [--type component|theme|template]
21st bookmark <id> --type <kind> [--remove]     # heart / un-heart
21st lists                          # your bookmark lists
21st list <listId>

21st teams                          # your teams
21st team <teamId>                  # a team's libraries
21st team-components <teamId> [--library <id>]

21st init --client cursor|claude|codex|vscode|devin [--write]      # write MCP config
21st install-skill                  # install the 21st skills globally
```
