CLI

The particles command-line tool lets you pull tokens into your codebase, export CSS, push existing token files, and automate syncing in CI. Developers use it to consume tokens; designers and admins can also push token files to bootstrap or migrate a project.

Installation

Available on npm as @particlesui/cli.

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

Authentication

The CLI authenticates via OAuth device flow — the same approach 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 the OS config directory:

# macOS
~/Library/Application Support/particles-ui/auth.json

# Linux (XDG_CONFIG_HOME takes precedence if set)
~/.config/particles-ui/auth.json
# or: $XDG_CONFIG_HOME/particles-ui/auth.json

# Windows
%APPDATA%\particles-ui\auth.json

Check the current auth state at any time:

particles auth status
particles auth logout

Init

Run particles auth login first, then particles init in your project root. The command walks you through an interactive setup:

Step	What you choose
Organization	Select from your organizations fetched from the platform.
Project	Select from the projects in that organization.
Export format	tailwind-v4, css, scss, style-dictionary, dtcg, json, ts, or js.
Output directory	Directory where the generated file will be written (e.g. src/styles).
File name	File name without extension (e.g. tokens). Extension is derived from format.

After the prompts, the CLI fetches the initial token file from the platform and writes it to disk, then creates particles-ui.json:

particles-ui.json

{
  "projectId": "018fde70-0000-7000-8000-000000000001",
  "organizationId": "018fde70-0000-7000-8000-000000000002",
  "format": "tailwind-v4",
  "outputDestination": "src/styles/tokens.css"
}

For CI or scripted setup, skip the prompts with flags:

particles init --yes \
  --org-id <id> \
  --project-id <id> \
  --format tailwind-v4 \
  --output-dir src/styles \
  --file-name tokens

Commands

token-studio sync

Fetch tokens and write them to outputDestination (configured during init). Works like npm install — by default it pulls the latest published release. If no releases exist yet, it falls back to the branch HEAD. This command replaces the entire output file — it is the source of truth, not a partial update.

# Pull latest release (default — recommended for production)
particles token-studio sync

# Pull from a branch HEAD (useful during active development)
particles token-studio sync --branch rebrand-2025

# Pin to a specific release snapshot
particles token-studio sync --version 1.2.3

# Sync and fail CI if any contrast pairs fail WCAG AA
particles token-studio sync --wcag-level AA

src/styles/tokens.css (written by sync)

@import "tailwindcss";

@theme {
  --color-blue-100: oklch(0.93 0.03 245);
  --color-blue-500: oklch(0.62 0.19 261);
  --color-neutral-50: oklch(0.98 0 0);
  --color-neutral-900: oklch(0.09 0 0);
  --color-background: var(--color-neutral-900);
  --color-primary: var(--color-blue-500);
  --spacing-1: 0.25rem;
  --radius-md: 0.5rem;
}

Token variables are sorted alphabetically by type group, then by group path and name (with numeric-aware ordering so 100 sorts before 200 and 1000), matching the order you see in the Studio token list.

token-studio export

Export resolved tokens in a chosen format — useful for piping into other tools or generating multiple artifacts from one source of truth.

# Tailwind v4 CSS (default)
particles token-studio export --format tailwind-v4

# Write to a file instead of stdout
particles token-studio export --format css --output ./styles/tokens.css

# Export from a specific branch
particles token-studio export --format scss --branch rebrand-2025

# Pin to a published release snapshot
particles token-studio export --version 1.2.3 --format tailwind-v4

# TypeScript theme object — drops into MUI createTheme() or styled-components ThemeProvider
particles token-studio export --format ts --output ./src/theme.ts

# Plain JS theme object (same shape, no type annotations)
particles token-studio export --format js --output ./src/theme.js

# Other formats
particles token-studio export --format style-dictionary
particles token-studio export --format dtcg
particles token-studio export --format json

# Pipe into another tool
particles token-studio export --format json | jq '.[] | select(.type == "color")'

The ts and js formats emit a single named export grouped by token type — colors, spacing, fontSize, radii, shadows, and so on — with groupPath nested underneath. Composition tokens are emitted as parsed nested objects. The TS variant appends as const and an export type Theme = typeof theme alias so consumers get autocomplete for every token path. Semantic tokens emit fully resolved values (a snapshot) since JS objects can't reference siblings cleanly.

src/theme.ts (excerpt)

export const theme = {
  colors: {
    brand: {
      primary: { "500": "#3b82f6", "600": "#2563eb" },
    },
    background: { default: "#ffffff" },
  },
  spacing: { sm: "8px", md: "16px" },
  fontSize: { base: "16px" },
  radii: { md: "8px" },
  shadows: { sm: "0 1px 2px rgba(0,0,0,0.08)" },
} as const

export type Theme = typeof theme

styled-components — drop in directly

import { ThemeProvider } from 'styled-components'
import { theme } from './theme'

export function App({ children }) {
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>
}

MUI — spread into createTheme()

import { createTheme, ThemeProvider } from '@mui/material'
import { theme as tokens } from './theme'

const muiTheme = createTheme({
  palette: {
    primary: { main: tokens.colors.brand.primary['500'] },
    background: { default: tokens.colors.background.default },
  },
  typography: { fontSize: parseInt(tokens.fontSize.base) },
  shape: { borderRadius: parseInt(tokens.radii.md) },
})

export function App({ children }) {
  return <ThemeProvider theme={muiTheme}>{children}</ThemeProvider>
}

token-studio push

Push a local token file into a project branch — useful for bootstrapping a new project from an existing design file, migrating a legacy token library, or scripting bulk token updates from CI. Targets main by default; use --branch to push to a feature branch.

Push requires the tokens:write permission, which is granted to Admin and Designer roles. Developer accounts have read-only CLI access and cannot push.

# Preview changes without applying them (dry run)
particles token-studio push --file ./tokens/globals.json --dry-run

# Apply changes — JSON is auto-detected (DTCG, Tokens Studio, Style Dictionary, or Particles)
particles token-studio push --file ./tokens/globals.json

# Push to a feature branch instead of main
particles token-studio push --file ./tokens/globals.json --branch rebrand-2025

# Push a CSS file (custom properties are parsed automatically)
particles token-studio push --file ./styles/tokens.css

# Push SCSS variables
particles token-studio push --file ./styles/_tokens.scss

# Push a TypeScript theme object (evaluated locally, then uploaded as DTCG)
particles token-studio push --file ./src/theme.ts

# Same for plain JS
particles token-studio push --file ./src/theme.js

# Override the default tier assigned to tokens that don't declare one
particles token-studio push --file ./tokens/globals.json --tier semantic

The format is detected from the file extension. A --dry-run prints a summary of what would change without modifying any data in the project:

Dry run (no changes applied):
  + 12 tokens added
  ~ 3 tokens updated
  - 1 token removed

Extension	Parsed as
.json	Auto-detected: DTCG/W3C, Tokens Studio, Style Dictionary, or Particles JSON
.css	CSS custom properties — :root { --color-brand: #3b82f6; }
.scss	SCSS variables — $color-brand: #3b82f6;
.js	JS theme object exported as export const theme = { … }
.ts	TypeScript theme object — as const and export type lines are stripped before evaluation

JS and TS files are evaluated locally in a sandboxed context before upload — no code runs on the Particles platform. Composition tokens represented as nested objects in JS/TS become individual flat leaf tokens after import. Use DTCG JSON if you need to preserve composition token structure.

token-studio branch create

Create a new branch forked from an existing one. Tokens from the source branch are copied into the new branch so you can experiment without touching the original. Defaults to forking from main.

Requires the branch:create permission — granted to Admin role or Designers with elevated branch permissions on the project.

# Fork from main (default)
particles token-studio branch create rebrand-2025

# Fork from a specific branch
particles token-studio branch create rebrand-sub --from rebrand-2025

migrate --scalable

Make Scalable — turn a flat or messy token set into a layered primitive → semantic system. It extracts cleanly-named primitives from your raw values and re-points the genuine semantics onto them in place, so token ids and names are preserved and every rendered value stays identical (non-breaking). High-confidence mappings are applied automatically; weaker ones are listed in a report for you to review.

# Preview + apply on the current branch
particles migrate --scalable

# Target a branch and only auto-accept very confident mappings
particles migrate --scalable --branch rebrand-2025 --min-confidence 0.85

Make Scalable is a Business plan capability. The same flow is available as a button in Studio and the Figma plugin, and a single Revert last run restores the pre-migration state.

Theme commands

Manage sub-brand themes and generate per-theme CSS blocks. Themes are project-scoped token overrides applied via a data-theme attribute.

theme list

particles theme list

theme generate

Generate a [data-theme="name"] { … } CSS block for a single theme.

# Write to stdout
particles theme generate dark

# Write to a file
particles theme generate dark --out src/themes/dark.css

theme generate-all

Generate one CSS file per theme into a directory.

particles theme generate-all --out-dir src/themes

Multi-level modules

For a multi-level product that consumes Foundation / Brand modules, check whether any linked module has a newer release than the one your product is pinned to, and preview the diff before adopting it in the Studio. Both commands are read-only — accepting an update is done in Project → Token modules.

# List linked modules — pinned release vs latest, and updates available
particles token-studio modules status

# Dry-run diff of a pending module update (added / removed / changed / conflicts)
particles token-studio modules preview <refId>

Standalone projects have no modules — modules status simply reports that. The older foundation sync command is deprecated in favour of modules; see Token architecture.

CI / GitHub Actions

A typical CI step that syncs tokens and enforces WCAG AA contrast:

.github/workflows/tokens.yml

- name: Sync design tokens
  run: |
    npx @particlesui/cli auth login  # uses PARTICLES_TOKEN env from CI secrets
    npx @particlesui/cli token-studio sync --version ${{ github.ref_name }} --wcag-level AA