Skip to content
UI
On this page

CLI

Use CLI commands and options. Preview changes before you overwrite source.

Copy component source into an existing React project. Use the CLI to configure StyleX, install components, and update copied files.

Prerequisites

  • Install Bun, npm, pnpm, or modern Yarn (version 2 or later).
  • Use a React application with TypeScript.
  • Get permission to add packages and files.
  • Use Vite, TanStack Router, TanStack Start, React Router, Next.js App Router, or Astro.

Vite integrations use Rolldown Babel. Next.js App Router requires Node 24 or later and webpack. React Router supports client mode and framework mode. The init command does not support React Router RSC mode or Next.js Pages Router.

The CLI supports Bun, npm, pnpm, and Yarn 2 or later.

init

Run init from the project root:

The command detects the framework. It installs base source, StyleX dependencies, and the Oxlint plugin. It configures aliases, build plugins, and root styles. It keeps existing project code. Unsupported configuration or conflicting settings stop the command. See Installation for setup details.

Use --framework when detection finds more than one supported framework. Accepted values are vite, tanstack-router, tanstack-start, react-router, next, and astro.

Design system guidance

Interactive init offers DESIGN.md, update AGENTS.md, or do nothing. Press Enter to skip guidance. Noninteractive init skips guidance by default.

Select a file without a prompt:

Both file options contain the same design system instructions. They cover StyleX, semantic tokens, typography, layout, themes, component selection, and accessibility.

The instructions include light and dark color and shadow values, spacing values, and component sizes. They use Geist Sans and Geist Mono. Load these fonts in the application. Pixel equivalents assume a 16px root font size. Install components before you use them; init installs only base files.

The selected file stays in the target app directory, including shared UI setup. Init preserves text outside the marked Yopem UI section. Repeated init updates that section. Malformed or duplicate markers stop init. The other file stays unchanged. Use the same option to refresh guidance after a CLI update.

Use --dry-run with --guidance to preview the file without writes.

add

Initialize the project before you add components. Pass one registry item name:

The command installs component source, required shared files, and dependencies. It records installed files and their hashes in ui.json.

Source directories

Interactive init asks whether to customize source directories. Press Enter to keep the defaults. Choose yes to set each directory.

Init checks the target project for a src directory. Without src, it removes the src/ prefix from the defaults below. Noninteractive init uses detected defaults without a prompt.

Init saves the directories in ui.json. You can also set paths before init. This example changes UI component and hook directories:

Paths are relative to the project that contains ui.json. Use forward slashes. Keep existing manifest fields when you add paths.

KeyDefault directory
componentssrc/components
uisrc/components/ui
hookssrc/hooks
libsrc/lib
stylessrc/styles
themesrc/themes

Missing keys keep their defaults. The ui directory is independent of components. Set ui to change the destination for UI components.

For shared workspaces, init checks the UI package for src. It saves directory choices in that package's ui.json. The sourceRoot field records the import alias root: src or ..

Add and update use these directories and rewrite copied source imports. Paths must stay inside the project. Directories can overlap. The CLI rejects file destination conflicts.

Set each path before you install files in that directory. The CLI does not move tracked files. It rejects changed destinations for tracked files. Existing tracked layouts keep their current directories, including the earlier src/theme directory.

update

Review local changes before you update an installed item:

Use the base item to update installed shared files:

The update command rejects modified files unless you pass --force. Save local changes before you use force. Force can remove your changes:

Help and version

Run the CLI without arguments to show usage. Use --help or -h for the same result. Use --version or -v to show the installed CLI version:

These commands do not need a project. They exit successfully. Do not add arguments to help or version commands. Use flags, not help or version command names. Invalid commands or arguments exit with status 1.

Options

OptionCommandsPurpose
--framework <name>initSelect a supported framework.
--guidance <choice>initSelect design, agents, or none for design system instructions.
--ui <path>initUse an existing shared UI package. The path is relative to the target app.
--cwd <path>init, add, updateSet the target directory. The default is the current directory.
--registry <URL>init, add, updateSet the registry for this command. The default is https://ui.yopem.com/r.
--dry-runinit, add, updatePreview changes without writes or package-manager commands.
--forceadd, updatePermit source overwrites. Review the preview first.
--help, -hStandaloneShow usage.
--version, -vStandaloneShow the installed version.

Only help and version have short flags. Pass option values as separate arguments. Do not repeat flags. The init command accepts no item name and rejects --force. The add and update commands require one item name. They reject --framework, --ui, and --guidance.

Safe overwrites

The init and add commands keep local changes to installed source by default. The add command skips modified tracked files. The update command reports them as conflicts. Use --force with add or update only when you want to overwrite source.

Force does not bypass registry validation. It does not permit init to overwrite conflicting build configuration. Review conflicting exports and build configuration manually.

Dry run

Preview setup or installation before you change files:

Dry runs read the registry. They validate URLs, schemas, paths, and file integrity. They do not write files, create directories or temporary files, or run a package manager. They do not change ui.json, configuration, package manifests, lockfiles, or dependencies.

The plan lists writes, skipped files, conflicts, and dependency additions. It identifies forced source overwrites. Writes include tracking changes in ui.json. Dependency lists show requested package arguments, not resolved package versions. Init also lists prerequisites and setup changes for the app and shared UI package.

Resolve conflicts before installation. A real installation requires files to remain unchanged after the preview.

Registry

Pass --registry <URL> to use another registry. The setting applies to one command. The CLI does not store it in ui.json.

URLs must use HTTPS, except HTTP on localhost or loopback addresses. Do not include credentials, query strings, or fragments. For local development, pass the local registry explicitly:

Requests have a 30-second timeout for connection and JSON body reads. Timeout, network, HTTP status, and malformed JSON errors stop installation. The CLI makes no source, configuration, or dependency changes after these failures.

Monorepos

Use --cwd to target an app from the repository root:

The CLI detects the package manager from the app and workspace root. It supports Bun, npm, pnpm, and Yarn workspaces. Dependencies stay in the target package.

Use an existing named React package in the same workspace for shared components:

The --ui path is relative to the target app, not the repository root. Init installs base files in the UI package. It adds source exports and links the app. It configures StyleX to scan both packages. For Next.js, it also adds transpilePackages. It registers shared imports with the Yopem UI Oxlint rules. It keeps existing rule options and explicit opt-outs.

Shared imports use the package name, such as @acme/ui/components/ui/button. Later add and update commands use the name from the package's ui.json. Run init --ui for each consuming app. Pass --ui again when you repeat init. The init command does not migrate app-local components.