CLI

@aura-design/cli is the on-ramp for Aura. It wraps Next.js scaffolding and the shadcn CLI with Aura registries, tokens, rules, skills, and optional project tooling.

Invoke it with:

pnpm dlx @aura-design/cli@latest <command>

The published binary name is aura.

Quick start

New Next.js app with Aura fixtures:

pnpm dlx @aura-design/cli@latest init

Existing Next.js app (skips create-next-app):

pnpm dlx @aura-design/cli@latest setup
# or
pnpm dlx @aura-design/cli@latest setup --dir ./apps/web

See also Installation for adding every registry component via all.txt.

Commands

init

Creates a Next.js app with create-next-app, then applies Aura to the new (or current) project root:

1. Writes components.json with @aura and @aura-dev registries
2. Generates light/dark Radix scales into globals.css
3. Runs shadcn add for @aura/class-names, @aura/page-get-starter, @aura/css-main, @aura/rules, @aura/skill-aura, and @aura/skills
4. Runs the same scaffolding as blueprint, including gdp-ts proofs

pnpm dlx @aura-design/cli@latest init

setup

Same Aura apply step as init, for a project that already has a package.json. Does not run create-next-app.

pnpm dlx @aura-design/cli@latest setup --dir .

link

Downloads the canonical Aura components.json (shadcn config with @aura registry URLs) into your project. Useful when you only need the registry config, not a full setup.

pnpm dlx @aura-design/cli@latest link
pnpm dlx @aura-design/cli@latest link --output ./apps/web/components.json

blueprint [projectDir]

Scaffolds Aura project tooling into any repo. It does not need a package.json. Blueprint detects the stack and picks modules from it:

A server-language manifest wins over a package.json that only builds assets, so a Laravel app with Vite is php with images. Go servers built only on net/http are not detected as backends. Pass --with bruno for them.

• Sonar outside Node writes a sonar-project.properties for the language and scripts/sonar.sh (up, setup, scan, report, full). It runs SonarQube and the scanner in Docker, so the project needs no npm. .NET uses dotnet-sonarscanner and no properties file. Node keeps the sonar:* scripts in package.json
• Bruno writes bruno/bruno.json, bruno/environments/local.bru with baseUrl on the stack's default port, a health.bru request, and .agents/rules/bruno.mdc, which asks agents to update the .bru request in the PR that changes an endpoint. bruno/.env is git-ignored

For a Next app, blueprint writes:

• The feature map: wiki/obsidian-*/02-Documentación/Feature-Map/Feature-Map.base (suffix from the package name without its scope, first segment stripped, for example @org/my-app gives app), plus .agents/rules/feature-map.mdc and .agents/skills/update-feature-map/. It is the only project documentation: one note per feature, updated in the PR that changes it. There is no progress log
• The vault layout: wiki/obsidian-*/ with 00-General/, 01-Identidad/, 02-Documentación/Feature-Map/, and 03-Configuración/, each with a README.md that says what belongs there and when an agent may write it. .obsidian/ is written for local Obsidian but git-ignored (wiki/**/.obsidian/). An older vault is migrated: Feature-Map/ moves to 02-Documentación/Feature-Map/ with its .base filter repointed, and 01-Identity/ moves to 01-Identidad/. If a project already tracks .obsidian/, run git rm -r --cached wiki/*/.obsidian once
• wiki/obsidian-*/01-Identidad/Image-Identity.md for image generation, on frontends
• .agents/skills/generate-brand-images/ (identity-aware Gemini landing images)
• Third-party audits are not installed. Re-running blueprint deletes the Emil and Vercel skill folders an older CLI copied into .cursor/skills/ and .agents/skills/
• The forms stack: .agents/skills/aura/rules/forms.md, .agents/skills/aura-forms/, and the @aura/form, @aura/field, @aura/use-dynamic-form, and @aura/web-validation registry items (ajv, ajv-formats, ajv-errors). Missing skill files are written, untouched older Aura copies are updated, and customized copies are kept unless you pass --force. A previous Aura copy of .agents/rules/components-forms.mdc is removed. A customized copy of that file is left in place. Components are added only when missing and when components.json has the @aura registry
• Agent files under .agents/, the one home for every agent. Blueprint writes a managed block (between <!-- aura:agents:start --> and <!-- aura:agents:end -->) into the root AGENTS.md that tells every agent to apply .agents/rules/ and load skills from .agents/skills/, and a CLAUDE.md that imports @AGENTS.md. Team text outside the block is kept. If .cursor/rules is still a symlink, blueprint removes it. If it is a real directory, blueprint moves each file into .agents/rules/ when that name is not already there, then removes the directory. Every skill in .cursor/skills/ moves to .agents/skills/: an identical copy is dropped, a differing copy is kept with a warning to merge it by hand. An empty .cursor/ is removed. What remains in .agents/rules/ is process policy (feature map, no comments, DESIGN.md pointer). Design guardrails live in .agents/skills/aura/, same layout as .agents/skills/shadcn/ (SKILL.md plus rules/*.md). - scripts/preflight.ts
• Upstream shadcn/ui skills via pnpm dlx skills add shadcn/ui (.agents/skills/shadcn)
• sonar-project.properties plus Sonar-related scripts / devDependencies
• .gitignore and .env.example entries for Sonar / Gemini keys
• gdp-ts: @gdp-ts/core, the ESLint preset, the agent skill, a typecheck script when one is missing, and starter proofs (session, org role, project role, plan entitlement, and deleteProject)

Also runs automatically at the end of init and setup.

On repos bootstrapped by an older CLI, blueprint removes the Project Brain agent files it used to install: .cursor/rules/self-documenting-system.mdc, .agents/rules/self-documenting-system.mdc, .cursor/skills/update-project-brain/, scripts/brain-progress.ts, and the brain:progress script when it still has the Aura value. Existing wiki notes stay where they are. It also deletes the Emil skill folders and react-best-practices / vercel-react-best-practices from .cursor/skills/ and .agents/skills/.

pnpm dlx @aura-design/cli@latest blueprint
pnpm dlx @aura-design/cli@latest blueprint ./apps/web --force --suffix my-app
npx @aura-design/cli@latest blueprint ./services/billing --with bruno --without sonar

Note: The docs page Agent blueprint is an agent runbook (Ejecuta + URL). It is not this CLI command, though the runbook may invoke aura blueprint when scaffolding is missing.

colors

--accent and --gray are the seeds. --background is an optional light canvas. The dark canvas is derived from the gray seed.

When --accent or --gray is omitted, the command prompts for the missing seed. It does not prompt for a background. When a flag value is not #rgb or #rrggbb, the command exits 1 and does not prompt.

The command prints a WCAG report. When the report contains a fail line, the command exits 1 and does not write globals.css. When the report contains a warn line and no fail line, the command still writes the file.

:root:not(.light) inside @media (prefers-color-scheme: dark) and .dark set the same custom properties.

pnpm dlx @aura-design/cli@latest colors --accent "#f84657" --gray "#8c7375"
pnpm dlx @aura-design/cli@latest colors --accent "#4015ca" --gray "#7254cb"

The command writes the first of these files that exists. The candidates are app/globals.css, src/app/globals.css, styles/globals.css, and src/styles/globals.css. When none exist, it creates app/globals.css.

typography generate

Interactive prompts for body size, small size, and a headline scale (ratio or explicit h6–h1). Writes a custom typography.css aligned with Aura’s fluid clamp() philosophy.

pnpm dlx @aura-design/cli@latest typography generate

spacing [target]

Rewrites Tailwind spacing utilities in .tsx files from the default 4px mental model to the closest 13px-based token (Aura’s --spacing).

pnpm dlx @aura-design/cli@latest spacing
pnpm dlx @aura-design/cli@latest spacing ./components
pnpm dlx @aura-design/cli@latest spacing --dir ./apps/web

Adding components

After init or setup, install individual registry items with the shadcn CLI and the @aura namespace:

pnpm dlx shadcn@latest add @aura/button

There is no Aura command that adds every component. Use the newline-delimited list at https://auradesignsystem.com/all.txt.

Related

• Installation — shortest path to a working Aura app
• Registry — how @aura/* items are distributed
• Namespace — @aura vs @aura-dev in components.json
• MCP — browse and install registries from Cursor
• Agent blueprint — agent runbook for existing projects
• gdp-ts — proof-carrying authz installed by init and blueprint