npm package: @humicdev/cli
Description: CLI for Humic — pull design tokens into your codebase
Latest version: 0.4.6

# @humicdev/cli

CLI for [Humic](https://humic.dev) — manage design tokens from the command line.

## Quickstart

```bash
npm install -D @humicdev/cli
```

### 1. Log in

```bash
npx humic login
```

Opens your browser to authenticate. Your credentials are saved to `~/.config/humic/credentials`.

For CI or agents, use a CLI token instead:

```bash
npx humic login --token cli_abc123
```

### 2. Initialize

Connect an existing design system to your project:

```bash
npx humic init
```

Or create a new design system:

```bash
npx humic new
```

Both commands generate a `humic.config.json` and write your token files.

Non-interactive mode (for agents and CI):

```bash
npx humic init --org acme --design-system main --tailwind --json
npx humic new --org acme --name "My DS" --template blank --json
```

### 3. Sync

Pull the latest tokens at any time:

```bash
npx humic sync
```

## Commands

Every command supports `--json` for structured output and `--help` for usage.

| Command | Description |
|---------|-------------|
| `humic login` | Authenticate (browser or `--token`) |
| `humic logout` | Log out and revoke token |
| `humic whoami` | Show current user and orgs |
| `humic init` | Set up Humic in current project |
| `humic new` | Create a new design system |
| `humic pull` | Fetch tokens and write to disk |
| `humic sync` | Sync tokens (with `--watch` and `--check`) |
| `humic config` | Manage CLI config (`set`/`get`) |
| `humic ds` | Manage design systems (`list`, `rename`, `setup`) |
| `humic tokens` | Manage tokens (`list`, `upsert`, `delete`, `rename`, `move`, `duplicate`, `unused`, `inconsistent`, `guidelines`) |
| `humic scales` | Manage color scales (`list`, `create`, `update`, `delete`) |
| `humic primitives` | Manage primitives (`list`, `create`, `update`, `delete`) |
| `humic activity` | View design system activity log |
| `humic validate` | AI-powered token usage validation |

## Configuration

`humic.config.json` in your project root:

```json
{
  "org": "my-org",
  "designSystem": "my-design-system",
  "outputs": {
    "css": "tokens.css",
    "claudeContext": ".humic/claude-context.md",
    "tailwind": "humic.tailwind.ts"
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `org` | Yes | Organization slug |
| `designSystem` | Yes | Design system slug |
| `outputs` | Yes | Map of output format to file path |

### Output formats

- `css` — CSS custom properties (light + dark mode)
- `claudeContext` — Markdown context document for AI agents
- `tailwind` — Tailwind CSS plugin with design tokens

## For AI agents

All commands accept `--json` for machine-readable output. Commands that operate
on a design system accept `--ds <slug>` (falls back to `humic.config.json`).

```bash
humic ds list --json
humic tokens list --ds my-ds --json
humic tokens upsert --ds my-ds --file tokens.json --json
humic scales create --ds my-ds --file scale.json --json
humic validate --ds my-ds --file src/Button.tsx --json
```

## Environment variables

- `HUMIC_API_KEY` — API key (fallback if not using `humic login`)
- `HUMIC_BASE_URL` — Override the API base URL (for local development)