Full command reference for the sora-cli tool — init, add, list, diff, doctor, and mcp.
sora-cli is a standalone CLI for installing components from any shadcn-compatible registry into your project. It defaults to the Sora UI registry, so it skips the extra step of registering the @soralabs scope that the shadcn CLI needs — but it also works against any other registry via --registry <url>.
Looking for dedicated documentation? Visit cli.soralabs.studio for the standalone documentation site with in-depth guides, architecture, registry authoring, and complete command references.
Commands
init
Initializes a new or existing project for Sora UI and shadcn-compatible registries. It automatically detects your framework (Next.js App Router, Vite, Remix, Astro), Tailwind CSS version (v3/v4), configures components.json, sets up the @/* import alias, and installs required utility dependencies (clsx, tailwind-merge).
add
Resolves the dependency tree for the requested component(s), writes files into your project, and installs npm dependencies with your detected package manager (bun/pnpm/yarn/npm).
add supports universal component specifiers:
- Bare names: searches the Sora UI registry first, then automatically falls back to shadcn/ui base components (
button,dialog,input, etc.) if not found. - Direct URLs: points straight to any remote registry JSON file.
- Local files: installs from a local schema JSON file (e.g.
./registry/card.json). - GitHub references: installs directly from a GitHub repository (
owner/repo/itemorgithub:owner/repo#branch/item). - Namespaces: resolves
@scope/itemusing custom registries defined in yourcomponents.json. - Automatic RSC Handling: intelligently adds or strips the
'use client'directive depending on whether your project uses React Server Components.
--yes matters most when an agent or script runs the CLI non-interactively:
without it, add prints a confirmation prompt and — since there's no TTY —
silently exits successfully without installing anything. Pair with --force
to also skip per-file overwrite prompts.
list
Lists every component the target registry exposes. Add --json for machine-readable output (safe to pipe — errors and status messages go to stderr, never mixed into the JSON on stdout).
diff
Read-only comparison of installed component files against the current registry content — reports drift without writing anything.
If files differ, re-run add <component> --force --yes to apply the update.
doctor
Diagnoses common project setup issues before you install anything: Node version, package manager/lockfile conflicts, components.json validity, path alias configuration, Tailwind/React versions, cn() util dependencies, registry reachability, and whether a newer sora-cli version is available.
mcp
Starts the Model Context Protocol (MCP) server or automates configuration for AI coding assistants.
Authoring a custom registry? If you are building your own component
registry, sora-cli also includes build (compiles source components to
shadcn-compliant schema JSON) and validate (verifies imports and schema
integrity). For in-depth guides, see the Sora CLI
Docs.
Options reference
| Flag | Description |
|---|---|
--cwd, -c <path> | Run as if started in <path> — for monorepos, e.g. packages/ui. Picks up that workspace's own tsconfig.json/components.json aliases. |
--path <path> | Custom component install path. Only changes where files are written, without affecting which config gets detected (unlike --cwd). |
--registry <name|url> | Product registry key (default: ui) or a full registry URL. Must be HTTPS unless targeting localhost/127.0.0.1. |
--force | Overwrite existing files without asking. |
--yes, -y | Skip the install confirmation prompt — for scripts/CI. |
--dry-run | Preview changes without writing files or installing packages. |
--silent, -s | Suppress per-file output, keep summary lines. |
--view | Print resolved file contents instead of writing them. |
--json | Output as JSON (list, doctor). |
--version, -v | Show the CLI version. |
--help, -h | Show the help message. |
Environment
SORA_NO_UPDATE_CHECK — set to disable the npm update check that runs on every invocation (printed to stderr, never mixed into --json output). Useful in CI.
How it works
The CLI resolves component dependencies across multiple origins, writes files into your project with your configured path aliases, and installs npm dependencies with your detected package manager.
- Universal Addressing: When an address is provided, the CLI automatically detects whether it is a direct HTTPS URL, local file path, GitHub repository reference, or a scoped namespace from
components.json.registries. - Shadcn Base Fallback: For bare component names (e.g.
button),sora-clichecks the primary registry first. If the item returns 404, it seamlessly falls back tohttps://ui.shadcn.comusing the style configured in yourcomponents.json. - Cross-Registry Dependencies: If a component from an external registry or URL depends on base primitives (like
buttonorutils), the CLI traverses and flattens the dependency tree, placing base components intocomponents/uiand rewriting import aliases so everything resolves out of the box.
Since components are copied into your project rather than installed as a package, diff is the way to check whether the registry has changed a component since you installed it, and add <component> --force --yes is how you apply that update.
Registry content isn't cryptographically signed, so only point --registry or custom URLs at sources you trust — files are written into your project and their dependencies are fed straight into your package manager.
Monorepos
Use --cwd <path> (or -c) to run add/diff/doctor as if the CLI had been started inside <path> — it picks up that workspace's own tsconfig.json/components.json aliases.
If you only need to change where files land without changing which config is read, use --path instead of --cwd.
See also
- Sora CLI Docs — standalone documentation site for Sora CLI
- Installation — initial project setup with shadcn/ui
- MCP — the
get_component_infoMCP tool returns the exactsora-clicommand to run for a given component - Troubleshooting — common registry/CLI issues
- GitHub repository
Changelog
Latest updates, weekly releases, and announcements.
Accessibility
How is accessibility with Sora UI?
Built by Axyl. A motion-first component registry for React.
Last updated: 10/30/2026