CLI Guide

Install & Explore

No global install is required—run commands with NPX and Node.js 18+. The CLI pulls the latest component data from the Nocta registry, so make sure you have network access when you execute commands.

npx nocta-ui --help

Set up configuration, Tailwind tokens, and baseline utilities in one step. The initializer validates your framework (Next.js, Vite + React, or React Router 7), ensures Tailwind CSS v4 is present, installs required runtime packages, and creates nocta.config.json tailored to your project layout.

npx nocta-ui init

Discover Components

Browse the registry directly from your project. Components are grouped by category with descriptions, variants, and size information so you can decide what to install.

npx nocta-ui list

Add UI Building Blocks

Install one or many components at once. The CLI resolves internal dependencies, writes files into the alias defined by nocta.config.json, normalizes imports (@/ or ~/), and installs any missing npm packages. If target files already exist, you will be asked whether to overwrite them.

npx nocta-ui add button card badge

Command Reference

`init`

Detects supported frameworks: Next.js (App or Pages Router), Vite + React, or React Router 7 (Framework Mode)
Requires Tailwind CSS v4 and optionally upgrades guidance if an older version is found
Writes nocta.config.json with defaults for tailwind.css, component, and utility aliases
Downloads shared utilities (lib/utils.ts) and base icons.ts from the registry
Injects Nocta design tokens into the configured Tailwind CSS entry file (@import "tailwindcss" is preserved)
Installs core dependencies: clsx, tailwind-merge, class-variance-authority, @ariakit/react, @radix-ui/react-icons
Rolls back created files if initialization fails partway through

`list`

Fetches the live component catalog from https://nocta-ui.com/registry
Prints categories with descriptions and every component's summary
Shows available variants and sizes where provided
Suggests npx nocta-ui add <name> for quick follow-up installation

`add <components...>`

Requires a valid nocta.config.json generated by init
Accepts multiple component names; nested dependencies are fetched automatically
Normalizes import aliases to @/ (Next.js, Vite) or ~/ (React Router 7)
Prompts before overwriting existing files in your component folder
Installs missing npm dependencies and reports satisfied or updated versions
Prints created file paths plus ready-to-copy import statements, variants, and size options

Configuration

nocta.config.json controls where files are written, which CSS file receives design tokens, and how import aliases are prefixed. Edit it if your project uses custom folders or alias conventions.

{
  "$schema": "http://nocta-ui.com/registry/config-schema.json",
  "style": "default",
  "tailwind": {
    "css": "app/globals.css"
  },
  "aliases": {
    "components": "components",
    "utils": "lib/utils"
  },
  "aliasPrefixes": {
    "components": "@",
    "utils": "@"
  }
}

Next.js App Router defaults to app/globals.css, components/ui, and lib/utils
Next.js Pages Router uses styles/globals.css, components/ui, and lib/utils
Vite + React resolves to src/App.css, src/components/ui, and src/lib/utils
React Router 7 resolves to app/app.css, app/components/ui, and app/lib/utils
Update aliases.components if you want files written somewhere else; the CLI always writes into <alias>/
Update aliasPrefixes if you use custom import prefixes (for example @ui instead of @/components)

Networking & Requirements

The CLI needs internet access to download the registry, component source files, and design tokens
Tailwind CSS v4 must already be installed and present in node_modules
React 18+ is expected; the dependency checker warns when required versions are missing or outdated
The installer respects your package manager (npm, yarn, or pnpm) by detecting existing lockfiles

With the CLI in place you can script installations, scaffold component collections, and keep projects aligned with the latest Nocta UI releases without leaving your terminal.