On this page

Command Line Interface

The Starwind CLI initializes Astro and supported React framework hosts, installs Runtime-backed styled components, manages optional Primitive source, and configures Starwind Pro. Run it from your project root with your package manager:

Starwind v3 is stable on npm’s latest tag. The commands on this page name that tag explicitly.

pnpx starwind@latest init

npx starwind@latest init

yarn dlx starwind@latest init

The examples below use the installed starwind executable for brevity. You can replace it with the matching package-runner form above.

init

Use init to create starwind.config.json, choose Astro or React, install the matching adapter, create the Starwind CSS file, and configure the project integration and path aliases.

starwind init
starwind init --framework react
starwind init --astro
starwind init --defaults

Option	Description
`-d, --defaults`	Use default values for all prompts.
`-p, --pro`	Initialize the project and configure Pro access.
`--framework <framework>`	Select `astro` or `react`.
`--astro`	Initialize for Astro.
`--react`	Initialize for React.

Choose only one of --framework, --astro, or --react. If the project has a legacy config, init offers to run migration before continuing.

Supported projects

Project host	Required project signal	Default source root	Guide
Astro	`astro` dependency or `astro.config.*`	`src`	Astro
Vite React	`react`, `vite.config.`, and `src/main.`	`src`	Vite React
Next.js App Router	`next` and `app/layout.` or `src/app/layout.`	`.` or `src`	Next.js
Next.js Pages Router	`next` and `pages/_app.` or `src/pages/_app.`	`.` or `src`	Next.js
TanStack Start with Vite	`@tanstack/react-start`, `vite.config.`, and `src/routes/__root.`	`src`	TanStack Start
React Router framework mode	`react-router.config.`, `vite.config.`, and `app/root.*`	`app`	React Router

Detection and preflight

With init --defaults, Starwind examines package.json and framework configuration before it selects Astro or React. Astro wins when an Astro dependency or config is present, including an Astro project that also uses React islands. A React dependency selects the public React adapter, then host detection resolves Vite, Next.js App Router, Next.js Pages Router, TanStack Start, or React Router framework mode.

Inside an Astro project, init --framework react --defaults configures React as a secondary target. It installs Astro’s React integration, writes React components to src/components/starwind-react, and keeps Astro as the primary config framework.

The public adapter value written to starwind.config.json is react for every React host. The host is a detected project plan that controls source roots, CSS ownership, theme placement, and package integration. It is not a separate config framework value.

Starwind validates the host shape before it installs adapter packages, creates directories, writes configuration, or changes application files. Unsupported or incomplete hosts stop at this preflight step with the missing integration point in the error message.

migrate

Use migrate to move an existing pre-Runtime Astro project to the Runtime setup.

starwind migrate
starwind migrate --yes --package-manager pnpm

Migration can back up the existing component folders, asks before overwriting conflicts, and keeps components that cannot be migrated marked as legacy. It migrates all safe components in one run; it does not accept individual component names.

Option	Description
`-y, --yes`	Skip confirmation prompts.
`-m, --package-manager <pm>`	Use `npm`, `pnpm`, or `yarn` for dependencies.

add

Use add to install Runtime-backed styled component source for the configured framework. With no component names, the CLI opens an interactive picker.

starwind add button dropdown
starwind add button --framework react
starwind add --all

The CLI resolves component dependencies and package requirements. A framework override installs the selected Astro or React target; the project config determines its destination.

Option	Description
`-a, --all`	Add every available uninstalled component.
`-y, --yes`	Skip confirmation prompts.
`-o, --overwrite`	Overwrite files that already exist.
`--framework <framework>`	Install the `astro` or `react` target.
`-m, --package-manager <pm>`	Use `npm`, `pnpm`, or `yarn` for dependencies.

update

Use update to refresh installed styled component source. Updating can overwrite local component changes, so inspect or commit your changes first. With no names, the CLI opens a picker for the selected framework.

starwind update button
starwind update button --framework react
starwind update --all --framework all
starwind update --all --dry-run

Option	Description
`-a, --all`	Update all installed components in scope.
`-y, --yes`	Skip confirmation prompts.
`--dry-run`	Preview changes without writing files.
`--diff [path]`	Show the planned diff for all files or one file.
`--view [path]`	Show new contents for all planned files or one file.
`--framework <framework>`	Target `astro`, `react`, or `all`.
`-m, --package-manager <pm>`	Use `npm`, `pnpm`, or `yarn` for required package updates.

Framework targeting

The framework selected by starwind init is the primary styled component target. Its source is written to componentDir. When a project intentionally keeps Astro and React styled source side by side, pass --framework to add or update:

starwind add button --framework react
starwind update button --framework react
starwind update --all --framework all

Additional targets use componentDirs.<framework>, such as componentDirs.react = "src/components/starwind-react" in an Astro-primary project. The framework flag changes the installed source target and destination; it does not create separate component documentation.

primitives

Use the primitives namespace when you want compile-ready Primitive adapter source in your project instead of importing only from @starwind-ui/astro or @starwind-ui/react.

starwind primitives add button checkbox
starwind primitives add button --framework react --to src/react-primitives
starwind primitives update button
starwind primitives list --framework all

primitives add options

Option	Description
`-a, --all`	Add all available primitives.
`-y, --yes`	Skip confirmation prompts.
`-o, --overwrite`	Overwrite files that already exist.
`--framework <framework>`	Target `astro` or `react`.
`--to <dir>`	Set the Primitive source destination.
`-p, --path <dir>`	Alias for `--to`.
`-m, --package-manager <pm>`	Use `npm`, `pnpm`, or `yarn` for dependencies.

primitives update accepts --all, --yes, --dry-run, --diff [path], --view [path], --framework <framework> (astro or react), and --package-manager <pm>.

primitives list accepts --json and --framework <framework> (astro, react, or all).

See Primitives for package imports, vendored-source ownership, framework targeting, and destination guidance. The CLI does not currently provide primitive remove/export commands, Runtime source add/eject commands, starwind add --primitives, or starwind update --primitives.

search

Search styled components, Starwind Pro blocks, or Primitive source before installing.

starwind search dropdown
starwind search hero --plan free --limit 5
starwind search --primitives button --framework react
starwind search button --json

Option	Description
`-p, --plan <plan>`	Filter Pro blocks by `free` or `pro`.
`-c, --category <value>`	Filter Pro blocks by category.
`-l, --limit <number>`	Limit results; defaults to `20` and caps at `50`.
`-o, --offset <number>`	Offset paginated results; defaults to `0`.
`--json`	Print structured JSON output.
`--primitives`	Search Primitive source.
`--framework <framework>`	For Primitive search, use `astro`, `react`, or `all`.

docs

Use docs to open documentation for one or more styled components. Use --json when a tool or script needs the documentation references as structured output.

starwind docs button dialog
starwind docs button --json

remove

Use remove to delete installed styled component source and update starwind.config.json. With no names, the CLI opens an interactive picker.

starwind remove button
starwind remove button --framework react
starwind remove --all --framework all

Option	Description
`-a, --all`	Remove every installed component in scope.
`--framework <framework>`	Target `astro`, `react`, or `all`.

Check project imports before removing a component. Removal always asks for confirmation.

setup

Starwind Pro is the CLI’s supported setup workflow. For a new project that needs paid Pro authorization, configure it during initialization:

starwind init --pro

For an existing project, use setup. Pro is currently the only setup task, so setup and setup --pro perform the same Pro configuration.

starwind setup
starwind setup --pro
starwind setup --yes --package-manager pnpm

Option	Description
`-p, --pro`	Configure Starwind Pro (currently the default).
`-y, --yes`	Skip confirmation prompts.
`-m, --package-manager <pm>`	Use `npm`, `pnpm`, or `yarn` if initialization is needed.

Setup ensures the project is initialized, configures paid authorization in starwind.config.json, creates or updates .env.local with a STARWIND_LICENSE_KEY placeholder, and ensures the env file is ignored by Git. Replace the placeholder with your license key, then install the exact block name returned by search or the Pro catalog:

starwind add @starwind-pro/component-name

Free @starwind-pro/* blocks can be installed after ordinary starwind init; they do not require init --pro, setup, or a license key. Paid blocks require the authorization configured by init --pro or setup. Use --overwrite with add only when existing Pro block files should be replaced.