npm package: @matchkit.io/cli
Description: CLI for MatchKit design system skills. Init projects, add components, manage your design system.
Latest version: 0.2.0

# @matchkit.io/cli

Command-line interface for MatchKit design system skills. Sync your design system, add components, and integrate with CI/CD pipelines.

## Features

- 🔐 **Browser-based authentication** - Secure OAuth flow via matchkit.io
- 📦 **Component management** - Add individual components with automatic dependency resolution
- 🔄 **Sync & update** - Pull latest design system updates from your MatchKit configuration
- 🤖 **CI/CD ready** - Use API keys for automated deployments
- 📊 **Status tracking** - See what's installed, what's available, and what's changed

## Installation

```bash
npm install -g @matchkit.io/cli
```

## Quick Start

```bash
# 1. Authenticate (opens browser)
matchkit login

# 2. Initialize your project
matchkit init

# 3. Pull your design system
matchkit pull
```

Your design system files are installed to `.claude/skills/[theme]-ui/` and work automatically with Claude Code, Cursor, VS Code, and Windsurf.

## Commands

### `matchkit login`

Authenticate with MatchKit. Opens your browser to sign in, then saves your API key locally.

```bash
matchkit login
```

### `matchkit init`

Initialize a MatchKit design system in your project. Links to your configuration on matchkit.io.

```bash
matchkit init
```

### `matchkit pull`

Download your latest resolved design system from MatchKit.

```bash
matchkit pull
```

### `matchkit add <component>`

Install a single component with its dependencies.

```bash
matchkit add button
matchkit add data-table
```

### `matchkit list`

Show all 27 components with their installation status.

```bash
matchkit list
```

### `matchkit status`

Show current configuration, theme, version, and sync status.

```bash
matchkit status
```

### `matchkit diff`

Show what changed since your last pull.

```bash
matchkit diff
```

## Configuration

The CLI stores:
- **Project config**: `.matchkit/config.json` (in your project)
- **API key**: `~/.matchkit/credentials` (global, never committed)

### .matchkit/config.json

```json
{
  "$schema": "https://matchkit.io/schemas/config.json",
  "configId": "cfg_a1b2c3d4e5f6",
  "version": 3,
  "theme": "soft",
  "accent": "#14B8A6",
  "overrides": { "radius": "xl", "button-style": "ghost" },
  "componentsDir": "src/components/ui",
  "skillDir": ".claude/skills/soft-ui",
  "registryUrl": "https://matchkit.io/api/registry"
}
```

## CI/CD Usage

For automated deployments, set the `MATCHKIT_API_KEY` environment variable:

```yaml
# GitHub Actions
- name: Pull MatchKit design system
  env:
    MATCHKIT_API_KEY: ${{ secrets.MATCHKIT_API_KEY }}
  run: |
    npm install -g @matchkit.io/cli
    matchkit pull
```

Get your API key from https://matchkit.io/app/keys

## How It Works

1. **Authentication**: Browser OAuth flow creates an API key
2. **Configuration**: Links your project to your MatchKit design system
3. **Resolution**: Server-side resolution generates your personalized skill
4. **Download**: ZIP download with all components, tokens, and documentation
5. **Extraction**: Files land in `.claude/skills/[theme]-ui/`

## Requirements

- Node.js 18 or later
- A MatchKit account (free tier available at https://matchkit.io)

## Links

- **Website**: https://matchkit.io
- **Documentation**: https://matchkit.io/docs
- **Dashboard**: https://matchkit.io/app
- **Repository**: https://github.com/Maes9/matchkit
- **Issues**: https://github.com/Maes9/matchkit/issues

## License

MIT