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:

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.

npx frontfriend init [options]

Options:

--force - Force refresh tokens, ignoring cache

Examples:

# Initialize tokens
npx frontfriend init

# Force refresh tokens
npx frontfriend init --force

status

Check your Frontfriend configuration and cache status.

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.

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:

# 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 for the full workflow.

download

Download pre-built components to your project.

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:

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

npx frontfriend clean

Configuration

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

Config Format

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

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

Permission errors

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

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

Behind a proxy

Set standard Node.js proxy environment variables:

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