CLI
The shadcn CLI copies a Nexus UI component, the helpers it imports and its npm packages into your project with one command. This page is the reference; the Quick Start is the walkthrough from an empty folder.
See what add does
Pick something to add and run it. The terminal shows each step the shadcn CLI takes and the tree shows the files that land in your project.
What shadcn add does
Simulated — nothing runs on your machine
- my-app
- .env.local
- components.json
- next.config.ts
- package.json
- tsconfig.json
Pick an item and press Run. File lists and dependencies match the real wheel-selector registry entry.
Before you start
You need a Next.js project with Tailwind CSS and the @/ import alias, and a components.json file in its root. Both come from the Quick Start; if you already have a project, run this from its root:
npx shadcn@latest init -dIt creates components.json and src/lib/utils.ts (the cn() helper every Nexus UI component imports) and installs clsx and tailwind-merge. Without -d it asks you to choose a style.
Connect the @nexus-labs registry
A registry is a web address the CLI downloads components from. @nexus-labs is the short name you give the Nexus UI one. Connect it once per project:
npx shadcn@latest registry add "@nexus-labs=https://www.nexus-ui.com/api/registry/{name}"This adds the entry below to components.json for you (if the entry already exists it is left alone):
"registries": {
"@nexus-labs": "https://www.nexus-ui.com/api/registry/{name}"
}{name} is a placeholder that stays exactly as written. When you ask for @nexus-labs/glow-button, the CLI swaps in glow-button and downloads https://www.nexus-ui.com/api/registry/glow-button. The part before the slash picks the registry, the part after it picks the item.
Install free components and blocks
npx shadcn@latest add @nexus-labs/glow-button
npx shadcn@latest add @nexus-labs/pricing-sectionYou can list several names in one command. Every component and block page shows its exact command in the Install box; copy it from there. The CLI shows what it will write and asks you to confirm, then:
- writes the component files, usually under
src/components/<name>/; - writes the helpers they import, such as
src/lib/ui-sounds.tsfor components that make sound; - installs the npm packages they list, such as
framer-motion, with your package manager; - may add the Inter font setup so the component matches its preview (the
nexus-fontitem).
Without connecting the registry, a free item can also be installed straight from its address. It still needs components.json:
npx shadcn@latest add https://www.nexus-ui.com/api/registry/wheel-selectorInstall Pro components and blocks
Pro items are served only to Pro plans. The CLI sends your API key with each request, so there are three things to set up once: the key, a line in .env.local, and a header in components.json.
- Create the key at nexus-ui.com/dashboard/api-key (a Pro plan is required) with Generate key. Copy it straight away: it starts with
nxs_and is shown only once. - Save it in .env.local in your project root, next to
package.json:A new Next.js project already ignoresNEXUS_API_KEY=nxs_your_key_here.env*files in git. Never commit the key. The CLI also reads.env, or a variable set in your shell. - Add the header in components.json. Put this entry inside the outermost braces, next to
"aliases". If a"registries"entry is already there from the step above, replace it:Leave"registries": { "@nexus-labs": { "url": "https://www.nexus-ui.com/api/registry/{name}", "headers": { "Authorization": "Bearer ${NEXUS_API_KEY}" } } }${NEXUS_API_KEY}as written: the CLI replaces it with the value from.env.localwhen it runs. The key itself never goes into this file. - Install, from the project root:
npx shadcn@latest add @nexus-labs/particle-reveal npx shadcn@latest add @nexus-labs/text-animations
Errors
- NEXUS_API_KEY is missing. The CLI could not find the variable. Check the file name, that it is in the folder you run the command from, and that the line is
NEXUS_API_KEY=nxs_...without quotes or spaces. - 401 Unauthorized. The key is not accepted: it was copied wrong, you generated a newer one, or your Pro plan has ended. Generate a key again and update
.env.local. - Unknown registry @nexus-labs. The
registriesentry is missing, orcomponents.jsonis no longer valid JSON.
Useful options
npx shadcn@latest add @nexus-labs/glow-button --dry-run
npx shadcn@latest add @nexus-labs/glow-button --view
npx shadcn@latest add @nexus-labs/glow-button --diff
npx shadcn@latest add @nexus-labs/glow-button -y
npx shadcn@latest add @nexus-labs/glow-button -o--dry-runlists what would change without writing anything.--viewprints the files, and--diffcompares them with the ones you already have.-yskips the confirmation question.-ooverwrites files that already exist, including edits you made to them. Without it the CLI asks before replacing a file.-p <path>chooses the folder the component is written to.
Monorepos
Point the CLI at the workspace package that holds your app with -c:
npx shadcn@latest init -d -c ./apps/web
npx shadcn@latest registry add "@nexus-labs=https://www.nexus-ui.com/api/registry/{name}" -c ./apps/web
npx shadcn@latest add @nexus-labs/glow-button -c ./apps/webFor a Pro key, put .env.local inside apps/web.
Prefer to copy by hand?
You do not have to use the CLI. Every component page lists its source files with the exact path to save each one to; the Quick Start has the step by step.