# CLI Reference

Complete reference for Frontfriend CLI commands

# CLI Reference

The Frontfriend CLI helps you manage design tokens and components in your project.

## Installation

The CLI is included when you install the Frontfriend package. For the default Tailwind CSS v4 setup, install the `next` tag:

```bash
npm install @frontfriend/tailwind@next tw-animate-css
```

## Global Options

All commands support these global options:

- `--verbose` - Enable verbose output for debugging
- `--help` - Show help for any command

## Commands

### init

Initialize or update design tokens from your Frontfriend project.

```bash
npx frontfriend init [options]
```

**Options:**
- `--force` - Force refresh tokens, ignoring cache

**Examples:**
```bash
# Initialize tokens
npx frontfriend init

# Force refresh tokens
npx frontfriend init --force
```

### status

Check your Frontfriend configuration and cache status.

```bash
npx frontfriend status
```

**Output includes:**
- Configuration file location and validity
- ff-id from config
- Cache status and age
- Token summary

### migrate

Migrate existing shadcn components into Frontfriend component config.

```bash
npx frontfriend migrate [options]
```

**Options:**
- `--component <name>` - Component to migrate, or `all` to scan the UI directory
- `--input <path>` - Path to a specific shadcn component source file
- `--output <path>` - Custom output JSON path
- `--no-push` - Do not push migrated config to Frontfriend cloud
- `--keep-shadcn-classes` - Keep raw shadcn classes instead of rewriting them to Frontfriend tokens

**Examples:**
```bash
# Migrate all shadcn components
npx frontfriend migrate

# Migrate one component
npx frontfriend migrate --component button

# Migrate locally without pushing to Frontfriend cloud
npx frontfriend migrate --no-push
```

See [Migrate from shadcn](/docs/legacy/migrate-from-shadcn/) for the full workflow.

### download

Download pre-built components to your project.

```bash
npx frontfriend download <components...> [options]
```

**Arguments:**
- `<components...>` - Component names to download (or `all` for all components)

**Note:** When using `all`, the command will download both standard components and any custom components specific to your ff-id.

**Options:**
- `-f, --framework <framework>` - Framework version (react or vue)
- `-o, --output <path>` - Custom output directory
- `--registry <generation>` - Registry generation (`v4` or `legacy`)
- `--overwrite` - Overwrite existing files

**Examples:**
```bash
# Download a Tailwind v4 React component
npx frontfriend download button -f react --registry v4

# Download all legacy React components
npx frontfriend download all -f react --registry legacy

# Download specific Vue components
npx frontfriend download button card -f vue

# Download to custom directory
npx frontfriend download accordion -f react -o ./src/components

# Download and overwrite existing files
npx frontfriend download button -f react --overwrite
```

**Post-download:** After successful downloads, the CLI will display any required dependencies that need to be installed.

### clean

Clear the Frontfriend token cache.

```bash
npx frontfriend clean
```


## Configuration

The CLI reads configuration from `frontfriend.config.js` in your project root.

### Config Format

```js
// CommonJS
module.exports = {
  'ff-id': 'your-project-id',
  'aliases': {
    'ui': '@/components/ui'
  }
}

// ES Module
export default {
  'ff-id': 'your-project-id',
  'aliases': {
    'ui': '@/components/ui'
  }
}
```

### Config Options

- `ff-id` (required) - Your Frontfriend project ID
- `aliases` (optional) - Path aliases for component downloads
  - `ui` - Where UI components should be downloaded


## Exit Codes

- `0` - Success
- `1` - General error
- `2` - Configuration error
- `3` - Network error
- `4` - Invalid arguments

## Troubleshooting

### Command not found

Ensure you're using `npx` or have added to package.json scripts:

```json
{
  "scripts": {
    "ff:init": "frontfriend init",
    "ff:download": "frontfriend download"
  }
}
```

### Permission errors

On Unix systems, you may need to make the CLI executable:

```bash
chmod +x node_modules/@frontfriend/tailwind/dist/cli.js
```

### Behind a proxy

Set standard Node.js proxy environment variables:

```bash
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
```