# Command Line Interface

The Starwind CLI initializes Astro or React projects, 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 or React, 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 --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.

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

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

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

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

```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 <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](/docs/getting-started/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.

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

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

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

```bash
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:

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