# CLI reference

The commands that connect tokens, source and agent workflows.

The CLI is included in `@frontfriend/tailwind`. Run each command’s `--help` for the options supported by your installed version.

## Connect a Design System first

Every project starts from a Design System:

```bash
npx frontfriend login
npx frontfriend setup --ff-id YOUR_DESIGN_SYSTEM_ID
```

Commands that work on the Design System need its `ff-id` in `frontfriend.config.js`: `init`, `migrate`, `download`, `update`, `add`, `publish`, `diff`, `eject`, `restore`, `upgrade-config`, `design` and `agents configure`. When the `ff-id` is missing, they check that before anything else. They print `No Design System connected to this project` with the create-or-connect steps, exit with code 1 and do not change the project. `status` keeps reporting and lists the missing Design System first.

An `ff-id` that does not match a Design System reports `Design System "…" was not found`. One your account cannot access reports `Design System "…" is not accessible with your current Frontfriend login or permissions`. An operation your workspace role or plan does not allow reports `Frontfriend denied this operation on Design System "…"` with the reason.

## Tokens and diagnostics

```bash
npx frontfriend init
npx frontfriend init --force
npx frontfriend status
npx frontfriend check
npx frontfriend clean
```

`init` fetches and prepares tokens. `status` inspects configuration and cache state. `check` validates token configuration. `clean` clears the token cache. Regenerate after cleaning before relying on cached builds.

## Component downloads

```bash
npx frontfriend download button accordion -f react --primitive base --registry v4
```

| Option | Meaning |
| --- | --- |
| `-f, --framework` | `react` or `vue` |
| `-p, --primitive` | `radix`, `base`, `aria`, or `reka` |
| `--registry` | `v4` or `legacy` |
| `-o, --output` | Destination directory |
| `--overwrite` | Replace existing files deliberately |

`all` requests the complete applicable catalogue. Start with named components and review changes before choosing a broad download. The target must be a supported framework/primitive pair and your project needs an `ff-id`.

## Migration and recovery

```bash
npx frontfriend migrate --help
npx frontfriend migrate --component button
npx frontfriend upgrade-config --help
npx frontfriend restore --help
```

`migrate` always runs on the Frontfriend platform and writes a new Design System version after it saves a restore snapshot; it has no local-only mode. Migration can change component configuration; restore can change remote state. Inspect snapshots, output and the exact installed CLI behavior before accepting a write. See [Adopt Frontfriend](/docs/migrate-from-shadcn/). Moving from v3 is handled by the Frontfriend team, see [Migrate from v3](/docs/migration-v3-v4/).

## Authentication and agents

```bash
npx frontfriend login
npx frontfriend logout
npx frontfriend mcp --help
npx frontfriend agents install
npx frontfriend design sync
```

Complete login through the device flow. `mcp` starts the local authenticated stdio proxy. Skill installation and design sync write project-local context; inspect those changes before committing.

## Command availability

Run `npx frontfriend --help` to inspect the commands provided by your installed version. Use [Versions & releases](/docs/versioning/) to understand how component adoption relates to your Design System.