On this page

Command Line Interface

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

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, React, or Vue, 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 --framework vue
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`, `react`, or `vue`.
`--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

Vue support is in public beta. Direct package installs use @starwind-ui/vue@beta; run the CLI from starwind@latest. See Vue beta setup.

Detection and preflight

With init --defaults, Starwind examines package.json and framework configuration before it selects an adapter. Astro wins when an Astro dependency or config is present, including an Astro project that also uses React or Vue 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.

Inside Astro, init --framework vue --defaults configures the Vue integration and records componentDirs.vue as src/components/starwind-vue. Use add --framework vue for those islands. Standalone Vue hosts use vue as their primary framework; their source paths follow the host guide.

The public adapter value written to starwind.config.json is react for every React host. Starwind uses the detected host to choose source roots, CSS integration, theme placement, and required packages. The host is not stored as a separate 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`, `react`, or `vue` 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`, `vue`, 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`, `react`, or `vue`.
`--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, react, or vue), and --package-manager <pm>.

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

See Primitives for package imports, vendored-source ownership, framework targeting, and destination guidance.

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`, `vue`, 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`, `vue`, or `all`.

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

setup

Use setup to configure Starwind Pro in an existing project. For a new project that needs paid Pro authorization, configure it during initialization:

starwind init --pro

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.
`-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.