Introducing a new way to review your PRs.

Read the announcement

shadcn-ui / ui

Composable, accessible components with thoughtful defaults. Build your own component library with code you can customize, extend, and make your own.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / shadcn-cli-commands

shadcn CLI commands

Overview

The shadcn executable starts at packages/…/index.ts. It creates a Commander program named shadcn, reads the version from packages/…/package.json, installs SIGINT/SIGTERM handlers that exit cleanly, and registers the top-level commands in this order: init, apply, add, diff, docs, view, search, migrate, eject, info, build, mcp, preset, and registry. The package exposes that entry as the npm binary via package.json bin: ./dist/index.js; packages/…/tsup.config.ts builds src/index.ts plus public package entrypoints and copies src/tailwind.css into dist/tailwind.css after each build.

packages/…/init.ts is the main project setup flow. The init command, also aliased as create, validates CLI options with initOptionsSchema, resolves templates and preset inputs, protects existing components.json with backups, and delegates environment/project checks to preFlightInit. It can scaffold a missing project through createProject, select templates from packages/shadcn/src/templates, resolve preset URLs through packages/shadcn/src/preset/presets, resolve registry base config with resolveRegistryBaseConfig, and finally call exported runInit. runInit either delegates to a selected template's init/postInit hooks or writes components.json, merges discovered registries from ensureRegistriesInConfig, propagates design settings to linked workspace configs from getWorkspaceConfig, clears config caches, and installs the requested registry items through @shadcn/registry/internal/add-components.

packages/…/add.ts handles adding registry items to an existing or newly-created project. It loads env files, creates a temporary default config when components.json is missing, discovers registries referenced by item addresses with ensureRegistriesInConfig, warns for deprecated components based on the project base, and can prompt for selectable registry:ui items from getRegistry("@shadcn"). Its preflight path uses preFlightAdd: missing config prompts the user to run runInit, while an empty directory can trigger createProject followed by runInit. Normal installs call addComponents; --dry-run, --diff, and --view instead call dryRunComponents and print formatDryRunResult. Universal registry items bypass the local init flow and are sent directly to addComponents when not in dry-run mode.

packages/…/apply.ts applies a new preset to an existing project. It validates positional versus --preset input, parses --only theme,font, and uses preFlightApply to require both an existing project and components.json. Without a preset it opens or instructs the user to open the preset builder using resolveCreateUrl/promptToOpenPresetBuilder. With a preset, it resolves the active template, optionally records currently installed components from getProjectComponents, prompts about overwrites, loads env files, converts preset names/codes/URLs into an init URL with resolveApplyInitUrl, then wraps runInit in withFileBackup for components.json. After runInit, it syncs theme-level design settings to linked workspace configs unless --only excludes theme.

packages/…/build.ts is the current top-level registry build command. It preflights paths with preFlightBuild, reads registry.json plus any includes with readRegistryWithIncludes, creates a catalog with createRegistryCatalog, builds each item via createRegistryItem, writes one JSON file per item under the output directory, and writes either the generated catalog or a copy of the source registry.json as registry.json. packages/…/build.ts contains an older experimental registry:build command implementation that resolves file imports and validates item schemas, but packages/…/index.ts does not register it, so it is not reachable through the current registry command group.

packages/…/diff.ts is retained as a deprecated command that tells users to prefer add [component] --diff. It still resolves project config, warns on monorepo root usage, fetches the shadcn registry index, finds installed files, fetches registry payloads with fetchTree, applies the same transformer pipeline used for installed component generation (transformImport, RSC, CSS vars, Tailwind prefix, icons, menu, RTL, fonts, cleanup), and prints line diffs with the diff package.

packages/…/docs.ts prints documentation links for registry components. It resolves the base from --base or the current config style, validates it against preset bases, fetches the shadcn registry index, reads item.meta.links[base], normalizes legacy https://ui.shadcn.com links to the configured SHADCN_URL, and prints aligned human output or { base, results } JSON.

packages/…/eject.ts inlines the package CSS import into a user's Tailwind CSS file. runEject requires components.json unless the user is at a monorepo root, resolves tailwindCss from config, verifies an @import "shadcn/tailwind.css" with SHADCN_TAILWIND_IMPORT, resolves the package CSS from the project install or CLI distribution, replaces the import with a version-stamped block, and removes the shadcn dependency using the detected package manager. Deno is handled by editing package.json directly.

packages/…/info.ts reports detected project state. It blocks ambiguous monorepo-root execution, gathers getProjectInfo, getConfig, getProjectComponents, and a resolved project preset from packages/shadcn/src/preset/resolve, then prints or JSON-serializes project framework details, config aliases and resolved paths, registries, installed components, and documentation/code links. Its printPresetInfo helper is also reused by packages/…/preset.ts.

packages/…/migrate.ts is a dispatcher for named migrations. --list prints the hard-coded migration catalog (cn, icons, base-color, radix, rtl). The cn migration runs directly through migrateCn; the other migrations first run preFlightMigrate and require a valid config before dispatching to migrateIcons, migrateBaseColor, migrateRadix, or migrateRtl, passing --from, --to, --path, and --yes where relevant.

packages/…/preset.ts groups preset utilities under shadcn preset. preset decode validates and decodes a preset code using decodePreset, fills compatibility chartColor values from V1_CHART_COLOR_MAP when older codes omit them, and prints via printPresetInfo or JSON. preset url prints the create URL, preset open opens it in a browser, and preset resolve inspects the current project config and framework to derive the current preset. The group falls back to Commander help when invoked without a subcommand.

packages/…/search.ts and packages/…/view.ts are read-only registry inspection commands. Both load env files, tolerate partial components.json by building a shadow config with configWithDefaults and rawConfigSchema.partial(), then try to upgrade to full getConfig. search validates --type filters, requires either explicit registries or configured registries in components.json, discovers missing namespace registries through ensureRegistriesInConfig without writing, resolves the target registry set with resolveSearchRegistries, validates explicit registry configs, runs searchRegistries, and prints either printSearchResults output or raw JSON. view discovers any registries referenced by item addresses, validates registry config for those items, fetches getRegistryItems, and writes the registry payload as JSON.

packages/…/mcp.ts serves and configures the MCP integration. Running shadcn mcp loads env files and calls serveStdio(createServer, { onerror }), keeping protocol traffic on stdout and transport errors on stderr. The nested shadcn mcp init command prompts for or accepts a client (claude, cursor, vscode, codex, opencode), writes that client's MCP config pointing at npx shadcn@latest mcp, and installs shadcn@latest either through updateDependencies when a shadcn config exists or directly through the detected package manager. Codex is special: it installs the dependency but prints instructions for editing ~/…/config.toml instead of writing into the project. packages/…/mcp.ts defines a deprecated registry:mcp warning command, but it is not registered by the current registry group.

packages/…/index.ts currently registers only registry add and registry validate. packages/…/add.ts writes registry namespace mappings into components.json when present or package.json otherwise. It accepts @namespace values looked up from getRegistries() and @namespace=https:/…/{name}.json values provided explicitly, rejects built-in registries, skips already configured registries, and preserves existing config keys while appending registries. packages/…/validate.ts validates local registry files with validateRegistry or GitHub registry sources with validateGitHubRegistrySource, prints aggregate counts and grouped diagnostics, and sets a non-zero exit code when the report is invalid.

Tests for these commands run under packages/…/vitest.config.ts, which aliases @shadcn/registry to source via ../registry/vitest.alias so mocks in command tests affect the same internal modules used by the CLI. The package is ESM-only and requires Node >=20.18.1 per packages/…/package.json.

Coupling

Risks