Cyclone UI - Command-Line Interface (CLI)
The Cyclone UI command-line interface application.
Table of Contents
Installing
Using pnpm:
pnpm add @cyclone-ui/cli
Using npm
npm install @cyclone-ui/cli
Using yarn
yarn add @cyclone-ui/cli
The Cyclone CLI downloads component source from the public R2 registry at
https://public.storm-cdn.com/cyclone-ui/registry, following the copy-and-own
workflow used by shadcn/ui. The bucket serves a registry.json catalog and
self-contained components/<name>.json files; no Worker API is required.
# Create components.json and the local component directory.
cyclone-ui init
# Browse the registry. `list` is an alias for `search`.
cyclone-ui search --query button
# Inspect or install registry components.
cyclone-ui view button
cyclone-ui add button
# Preview an installation or compare installed files with the registry.
cyclone-ui add button --dry-run
cyclone-ui diff button
# Inspect the current project configuration.
cyclone-ui info
# Generate a Tamagui config from design tokens, then compile it and its CSS.
cyclone-ui build --config razorwind.config.ts --output tamagui.config.ts
# Generate only the config, without compiling it.
cyclone-ui build-tokens --config razorwind.config.ts
# Validate a shadcn-format registry.
cyclone-ui registry validate registry.json
init writes a components.json file containing the public registry URL, output
path, and installed component manifest. add resolves internal component
dependencies, refuses to overwrite changed files unless --overwrite is
provided, updates package dependencies, and records the installed version and
files. Registry file paths are constrained to the configured component
directory.
In a second repository, use the installed cyclone-ui executable:
pnpm exec cyclone-ui init --path src/components/ui
pnpm exec cyclone-ui add button
pnpm install
Component dependencies are copied recursively. Imports between copied components
become relative imports, including subpath imports from nested files. Other
packages, including @cyclone-ui/helpers and @cyclone-ui/state, are added to
package.json with published version ranges. Existing dependency declarations
are preserved. Run your package manager to install newly added dependencies.
To use another public registry, pass --registry <url> to init, or change
registry in components.json. A URL ending in /registry.json is also accepted.
For a prerelease channel use the registry's /tags/<tag> URL. Explicit legacy
Worker registry URLs ending in /api continue to use the typed API client.
For a Next.js App Router project, enable React Server Component support with
cyclone-ui init --rsc, or add "rsc": true to your existing components.json.
This preserves registry directives, matching shadcn's RSC-enabled behavior.
Registry authors are responsible for supplying "use client" directives on
client-only components, hooks, and helpers. The CLI does not infer client
boundaries or add directives to unmarked files.
Set "rsc": false to remove module-level "use client" directives from installed
JavaScript and TypeScript files, following shadcn's RSC opt-out behavior.
Server/cache directives, function bodies, comments, and non-script files remain
unchanged. Omitting rsc preserves registry contents without transformation.
The add command also accepts --rsc to override the project setting for that
installation. Previews and diffs use the same transformed contents as writes.
To style components with Tamagui Tailwind
class names instead of style props, run cyclone-ui init --style tailwind, or
add "style": "tailwind" to your existing components.json. Components that
ship a Tailwind variant (Skeleton.tailwind.tsx) install it in place of the
default file, and @tamagui/tailwind is added to package.json. Style them
with className, for example <Skeleton className="h-[32px] w-1/2" />.
Cyclone defines no border width tokens and there is no Tailwind preflight, so
give borders a px width and a style, such as border-[1px] border-solid.
Animate class changes with Tamagui's transition prop, as the installed
components do. @tamagui/tailwind leaves it out of its prop types, so pass it
in a spread typed with TransitionProp from @tamagui/core.
Components without a variant install their Tamagui source, which renders
alongside Tailwind components with the same tokens and themes. For build-time
CSS extraction, add tamaguiPlugin({ components: ["@tamagui/tailwind"] })
from @tamagui/tailwind/vite to your Vite config.
Registry authors add a Tailwind variant by placing <Name>.tailwind.tsx next to
<Name>.tsx with the same exports.
build accepts the same --cwd, --config, --tokens, and --output options
as build-tokens. It compiles the generated config into .tamagui/ and writes
tamagui.generated.css in the working directory. The compiler is included with
the Cyclone CLI; no separate Tamagui CLI installation is required.
Configuration
Coding agent component protection
Coding agents must not change installed or added Cyclone UI component files unless
the user specifically instructs them to do so. components.json identifies the
configured component path and installed files. General feature, styling, or
application-fix requests do not authorize component edits, formatting, renames,
deletions, registry updates, or overwrites. Prefer supported props, composition,
application-owned wrappers, and theme configuration outside the installed files.
If changing a component is necessary, explain why and ask for specific instructions
first. Explicitly requested component additions or changes must remain scoped and
preserve unrelated installed files and local edits.
This guidance is included in the CLI's guidelines command (also exposed through
MCP), component command descriptions, and info output. info --json includes an
agentInstructions field. It is guidance for agents, not a filesystem write lock;
explicitly requested CLI operations remain available.
Development
This project is built using Nx. As a result, many of the usual commands are available to assist in development.
Building
Run nx build cli to build the library. The Razorwind Shell Shock plugin
extracts this repository's design system during the build and bakes its tokens,
components, icons and fonts into CLI commands and MCP tools. No Razorwind
configuration or generated snapshot is needed at runtime.
Running unit tests
Run nx test cli to execute the unit tests via
Vitest.
Linting
Run nx lint cli to run
ESLint on the package.