CLI

The particles command-line tool lets developers pull tokens into their codebase, export CSS, and automate token syncing in CI. This page is intended for engineers consuming tokens — designers manage tokens in the Studio or Figma plugin.

Installation

npm install -g @particles-ui/cli
# or
pnpm add -g @particles-ui/cli
# or run without installing
npx @particles-ui/cli <command>

Authentication

The CLI authenticates via OAuth device flow (the same flow used by gh auth login). Run the command below and approve the request in your browser.

particles auth login

Your session token is stored in ~/.particles/credentials.json. For CI environments, generate an API key in Settings → API keys and set it as an environment variable:

export PARTICLES_API_KEY=pk_live_...
# or per-command
particles pull --api-key pk_live_...

Init

Run particles init in your repo root to create a particles-ui.json config file. This stores your project ID, default branch, and icon library preference.

particles init

particles-ui.json

{
  "projectId": "018fde70-0000-7000-8000-000000000001",
  "branch": "main",
  "output": "./src/tokens",
  "format": "tailwind-v4"
}

Commands

sync (pull tokens)

Fetch the latest tokens and write them to the output directory. This is the primary command for keeping your codebase in sync with the design system.

particles token-studio sync [options]

Options:
  --project <id>      Project ID (overrides particles-ui.json)
  --branch <name>     Branch to sync from  [default: main]
  --version <semver>  Pull a specific release snapshot instead of branch HEAD
  --format <fmt>      Output format: tailwind-v4 | json | css  [default: tailwind-v4]
  --output <path>     Output directory  [default: ./src/tokens]

output: src/tokens/tokens.css

/* generated by particles-ui — do not edit */
@theme {
  --color-primary:    oklch(0.62 0.19 261);
  --color-background: oklch(0.09 0 0);
  --color-foreground: oklch(0.98 0 0);
  --spacing-1:        0.25rem;
  --radius-md:        0.5rem;
}

export

Export tokens to stdout in a chosen format — useful for piping into other tools.

particles token-studio export --format json | jq '.[] | select(.type == "color")'
particles token-studio export --format css --output ./styles/tokens.css
particles token-studio export --format scss --branch rebrand-2025
particles token-studio export --format style-dictionary
particles token-studio export --format w3c

import

Bulk-import tokens from a JSON or CSV file. Shows a dry-run diff by default; pass --apply to persist.

# Preview the import
particles token-studio import tokens-studio-export.json

# Apply the changes
particles token-studio import tokens-studio-export.json --apply

token

# List all tokens
particles token list

# Show a single token
particles token get color/primary

# Set a token value
particles token set color/primary "oklch(0.55 0.21 290)"

# Delete a token
particles token delete color/old-red

branch

# List branches
particles branch list

# Create a branch from main
particles branch create rebrand-2025 --from main

# Switch the CLI's active branch
particles branch use rebrand-2025

Foundation projects

If your project is linked to a foundation project, use these commands to manage cross-project inheritance:

# Link a foundation project
particles token-studio foundation link <project-id>

# Pull upstream changes (dry-run)
particles token-studio foundation sync

# Apply upstream changes, resolving conflicts
particles token-studio foundation sync --apply

CI integration

Pull tokens during your build step so your design system always reflects the latest approved state from main.

.github/workflows/tokens.yml

name: Pull design tokens
on:
  push:
    branches: [main]

jobs:
  tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @particles-ui/cli
      - run: particles token-studio sync --branch main --format tailwind-v4
        env:
          PARTICLES_API_KEY: ${{ secrets.PARTICLES_API_KEY }}
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: sync design tokens"