# 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: ```bash npx 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. ```bash 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 ` | 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](/docs/frameworks/astro/) | | Vite React | `react`, `vite.config.*`, and `src/main.*` | `src` | [Vite React](/docs/frameworks/vite-react/) | | Next.js App Router | `next` and `app/layout.*` or `src/app/layout.*` | `.` or `src` | [Next.js](/docs/frameworks/nextjs/#app-router) | | Next.js Pages Router | `next` and `pages/_app.*` or `src/pages/_app.*` | `.` or `src` | [Next.js](/docs/frameworks/nextjs/#pages-router) | | TanStack Start with Vite | `@tanstack/react-start`, `vite.config.*`, and `src/routes/__root.*` | `src` | [TanStack Start](/docs/frameworks/tanstack-start/) | | React Router framework mode | `react-router.config.*`, `vite.config.*`, and `app/root.*` | `app` | [React Router](/docs/frameworks/react-router/) | | Vite Vue · Beta | Vue 3.5+, official Vue plugin, `vite.config.*`, `src/main.*`, `src/App.vue` | `src` | [Vite Vue](/docs/frameworks/vite-vue/) | | Astro Vue · Beta | Astro host; select `--framework vue` | `src` | [Astro Vue](/docs/frameworks/astro/#vue-islands-beta) | | Nuxt 3 / 4 · Beta | Static `nuxt.config.ts`, root `app.vue` (3) or `app/app.vue` (4) | `.` / `app` | [Nuxt](/docs/frameworks/nuxt/) | | Laravel Inertia Vue · Beta | Official Vue starter and static resource entries | `resources/js` | [Laravel](/docs/frameworks/laravel-inertia-vue/) | | Quasar Vite · Beta | `@quasar/app-vite` v3, static config, SPA or SSR layout | `src` | [Quasar](/docs/frameworks/quasar/) | Vue support is in public beta. Direct package installs use `@starwind-ui/vue@beta`; run the CLI from `starwind@latest`. See [Vue beta setup](/docs/getting-started/installation/#vue-beta). ### 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. ```bash 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 ` | 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. ```bash 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 ` | Install the `astro`, `react`, or `vue` target. | | `-m, --package-manager ` | 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. ```bash 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 ` | Target `astro`, `react`, `vue`, or `all`. | | `-m, --package-manager ` | 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`: ```bash starwind add button --framework react starwind update button --framework react starwind update --all --framework all ``` Additional targets use `componentDirs.`, 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`. ```bash 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 ` | Target `astro`, `react`, or `vue`. | | `--to ` | Set the Primitive source destination. | | `-p, --path ` | Alias for `--to`. | | `-m, --package-manager ` | Use `npm`, `pnpm`, or `yarn` for dependencies. | `primitives update` accepts `--all`, `--yes`, `--dry-run`, `--diff [path]`, `--view [path]`, `--framework ` (`astro`, `react`, or `vue`), and `--package-manager `. `primitives list` accepts `--json` and `--framework ` (`astro`, `react`, `vue`, or `all`). See [Primitives](/docs/getting-started/primitives/) for package imports, vendored-source ownership, framework targeting, and destination guidance. ## search Search styled components, Starwind Pro blocks, or Primitive source before installing. ```bash starwind search dropdown starwind search hero --plan free --limit 5 starwind search --primitives button --framework react starwind search button --json ``` | Option | Description | | ------------------------- | ------------------------------------------------ | | `-p, --plan ` | Filter Pro blocks by `free` or `pro`. | | `-c, --category ` | Filter Pro blocks by category. | | `-l, --limit ` | Limit results; defaults to `20` and caps at `50`. | | `-o, --offset ` | Offset paginated results; defaults to `0`. | | `--json` | Print structured JSON output. | | `--primitives` | Search Primitive source. | | `--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. ```bash 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. ```bash starwind remove button starwind remove button --framework react starwind remove --all --framework all ``` | Option | Description | | ------------------------- | ---------------------------------------------- | | `-a, --all` | Remove every installed component in scope. | | `--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: ```bash starwind init --pro ``` `setup` and `setup --pro` perform the same Pro configuration. ```bash 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 ` | 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: ```bash 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.