Sora UI

Sora CLI

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

pnpm dlx @soralabs/cli@latest add text-effect

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/item or github:owner/repo#branch/item).
  • Namespaces: resolves @scope/item using custom registries defined in your components.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

FlagDescription
--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.
--forceOverwrite existing files without asking.
--yes, -ySkip the install confirmation prompt — for scripts/CI.
--dry-runPreview changes without writing files or installing packages.
--silent, -sSuppress per-file output, keep summary lines.
--viewPrint resolved file contents instead of writing them.
--jsonOutput as JSON (list, doctor).
--version, -vShow the CLI version.
--help, -hShow 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-cli checks the primary registry first. If the item returns 404, it seamlessly falls back to https://ui.shadcn.com using the style configured in your components.json.
  • Cross-Registry Dependencies: If a component from an external registry or URL depends on base primitives (like button or utils), the CLI traverses and flattens the dependency tree, placing base components into components/ui and 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

Built by Axyl. A motion-first component registry for React.

Last updated: 10/30/2026

On this page

Help keep SoraLabs moving.

Every contribution helps us build and maintain open-source tools for the community.

Sponsor on GitHub