Skip to main content
The Humic CLI gives you full control over your design system from the terminal. List tokens, create color scales, sync files to your project, validate code — all without opening the browser. Every command supports --json output, which makes the CLI a great fit for scripts, CI pipelines, and AI coding agents.

​
Prerequisites

  • A Humic account with at least one design system
  • Node.js 18 or later

​
Installation

You don’t need to install anything globally. Run every command with npx: 
npx @humicdev/cli <command>
Or install it as a dev dependency in your project: 
npm install -D @humicdev/cli
Then use it via npx humic <command> or add scripts to your package.json.

​
Step 1: Log in

Authenticate via your browser: 
npx @humicdev/cli login
This opens humic.dev in your browser. After signing in, your credentials are saved locally to ~/.config/humic/credentials. All future commands pick them up automatically.
You can also authenticate with a CLI token: npx @humicdev/cli login --token <your-token>. This is useful for CI environments or shared machines.
Verify that you’re logged in: 
npx @humicdev/cli whoami
You should see your email address and the organizations you belong to.

​
Step 2: Set up your project

Run init in the root of your project to connect it to a design system: 
npx @humicdev/cli init
This creates a humic.config.json in your project and writes the initial token files (CSS custom properties, Tailwind config, and usage context). You can skip the prompts by passing flags: 
npx @humicdev/cli init --org my-team --design-system brand
Starting from scratch? Use npx @humicdev/cli new to create a new design system and initialize your project in one step. You can pick a template like tailwind, bootstrap, or material to get started quickly.

​
Step 3: Pull tokens

After initializing, pull the latest tokens to your project: 
npx @humicdev/cli pull
This writes your design tokens as CSS custom properties and (optionally) a Tailwind config to your project. Run this whenever you want the latest version. To keep your project in sync automatically, use watch mode: 
npx @humicdev/cli sync --watch
This polls for changes every 30 seconds and writes updated files when something changes.

​
Commands

Below is the full list of commands. Every command that reads or writes design system data accepts --org <slug> and --ds <slug> to target a specific design system. If you’ve run humic init, these are read from your humic.config.json automatically.

​
Authentication

CommandDescription
loginAuthenticate via browser or CLI token (--token)
logoutLog out and revoke your CLI token
whoamiShow the currently authenticated user and organizations

​
Project setup

CommandDescription
initSet up Humic in the current project — creates humic.config.json and writes token files
newCreate a new design system and initialize. Supports --template (blank, tailwind, bootstrap, material)
pullFetch tokens and write to disk
syncSync tokens. --watch for continuous sync, --check to verify drift without writing (exit code 1 if out of sync)

​
Design systems

CommandDescription
ds listList all design systems across your organizations
ds rename --name <name>Rename a design system
ds setup --org <slug> --file <path>Create a complete design system from a JSON file (scales, primitives, tokens)

​
Tokens

CommandDescription
tokens listList tokens. Filter with --type and --status
tokens upsert --file <path>Create or update tokens from a JSON file (up to 500 at once)
tokens delete --names <a,b,c>Soft-delete tokens by name (comma-separated)
tokens rename --from <old> --to <new>Rename a token
tokens move --from-prefix <old> --to-prefix <new>Move tokens to a different group
tokens duplicate --source <name> --target <name>Duplicate a token
tokens unusedFind tokens not referenced by any other token
tokens inconsistentFind tokens with values outside your scales
tokens guidelinesShow the design system’s usage guidelines

​
Color scales

CommandDescription
scales listList all color scales
scales create --file <path>Create a scale from JSON ({ name, steps: [{ step, hexLight, hexDark }] })
scales update --name <name> --file <path>Update steps in an existing scale
scales delete --name <name>Delete a color scale

​
Primitives

CommandDescription
primitives listList primitives. Filter with --type
primitives create --file <path>Create primitives from a JSON file
primitives update --file <path>Update primitives (each entry needs an id)
primitives delete --ids <a,b,c>Delete primitives by ID (comma-separated)

​
Activity and validation

CommandDescription
activityView recent activity. --limit and --offset for pagination
validate --file <path>Validate a source file against your design system’s usage rules
config set <key> <value>Set a config value (e.g. anthropic-key)
config get <key>Get a config value

​
JSON output

Every command supports --json for machine-readable output. This is useful for scripts, CI, and AI agents: 
npx @humicdev/cli tokens list --json

{
  "total": 42,
  "tokens": [
    { "name": "color.primary", "type": "color", "value": "#36AA08" }
  ]
}

​
Using with AI coding agents

The --json flag makes the CLI work well as a tool for AI coding agents like Claude Code, Cursor, and Codex. Instead of connecting via MCP, agents can call the CLI directly. For example, in your agent’s configuration or system prompt, you can describe commands like: 
To list design tokens: npx @humicdev/cli tokens list --json
To sync files: npx @humicdev/cli pull --json
To validate code: npx @humicdev/cli validate --file src/Button.tsx --json
The agent can run these commands and parse the JSON output to understand your design system.

​
Code validation

The validate command checks your code against the design system’s rules — catching hardcoded colors, magic spacing values, and other violations. It returns a score and specific suggestions. This requires an Anthropic API key (used locally, no data is sent to Humic): 
npx @humicdev/cli config set anthropic-key sk-ant-...
npx @humicdev/cli validate --file src/components/Button.tsx

​
Checking for drift in CI

Use sync --check in your CI pipeline to verify that local token files match the source of truth: 
npx @humicdev/cli login --token $HUMIC_CLI_TOKEN
npx @humicdev/cli sync --check
This exits with code 0 if everything is in sync, or code 1 if files are outdated. No files are written.

​
Troubleshooting

Run npx @humicdev/cli login to re-authenticate. If you’re using a CI token, make sure it’s still valid in your Humic dashboard.
Make sure you’ve run npx @humicdev/cli init in your project, or pass --org and --ds explicitly. Run npx @humicdev/cli ds list to see all design systems you have access to.
Check your internet connection. If you’re behind a proxy or firewall, allow traffic to humic.dev.
This command requires a separate Anthropic API key. Set it with npx @humicdev/cli config set anthropic-key sk-ant-.... The key is stored locally and only used for local validation.