@particlesui/cli

Command-line interface for Particles UI — sync design tokens from Particles UI Studio into your codebase and generate themed CSS.

Installation

npm install -g @particlesui/cli
# or use without installing
npx @particlesui/cli --version

Quick start

# Authenticate
particles auth login

# Initialize a project
particles init

# Sync latest tokens
particles token-studio sync

Commands

particles init

Initialize Particles UI in the current project. Creates particles-ui.json and fetches an initial token file.

For multi-level projects with named platforms, the interactive wizard prompts for a platform after project selection and persists the choice to config. Standalone projects skip this step entirely.

particles init [options]

Options:
  -y, --yes                Skip interactive prompts
  --org-id <id>            Organization ID
  --project-id <id>        Project ID
  --format <format>        Output format (default: tailwind-v4)
  --output-dir <dir>       Output directory (default: src)
  --file-name <name>       Output file name without extension (default: globals)
  --platform-id <uuid>     Platform ID (multi-level projects only; auto-detected if omitted)

particles auth

particles auth login     # Login via OAuth device flow
particles auth logout    # Clear stored credentials
particles auth status    # Show current authentication status

particles migrate

Auto-discover existing design-token files in a directory and migrate them into a project — no need to know each file's format or run push per file. Scans for DTCG/W3C JSON, Tokens Studio, Style Dictionary, CSS custom properties, SCSS variables, and Particles-generated JS/TS theme exports (skipping node_modules, build output, package.json, and ordinary stylesheets). Shows an aggregated dry-run diff, then applies on confirmation.

Requires the Team plan or higher (enforced server-side). Sub-Team orgs see an upgrade prompt.

particles migrate [options]

Options:
  --path <dir>        Directory to scan (default: current directory)
  --project <id>      Target project id (defaults to particles-ui.json, else prompts)
  --branch <branch>   Target branch (default: main)
  --tier <tier>       Default tier for tokens that don't declare one (primitive|semantic|composition)
  --include <glob>    Only migrate files whose relative path matches this glob
  --yes               Skip the confirmation prompt (non-interactive / CI)
  --dry-run           Preview the migration without applying it
  --report <file>     Write a JSON migration report to this path
  --scalable          After migrating, run the legacy→scalable Scalability Pass (Business plan)
  --min-confidence <n> Auto-accept threshold for scalable mappings, 0..1 (default: 0.7)
  --cutover           BREAKING: adopt the clean names, drop the deprecated alias layer, and emit an
                      old→new code-reference rewrite report (Business plan). Explicit opt-in.

# Preview what would be migrated from ./tokens
particles migrate --path ./tokens --dry-run

# Migrate everything and write a report
particles migrate --path ./tokens --report migration-report.json

# Migrate, then run the scalable Scalability Pass (Business plan)
particles migrate --path ./tokens --scalable

# Tighten the auto-accept threshold (only bind mappings ≥ 0.85; skip the rest for review)
particles migrate --path ./tokens --scalable --min-confidence 0.85

# Later, when your Figma files and codebase are ready: the breaking cutover (writes a rename report)
particles migrate --path ./tokens --cutover --report cutover-report.json

The optional Scalability Pass (--scalable, Business plan) runs server-side over the just-migrated branch. It synthesizes a clean, value-preserving New token set (deduped primitives, a semantic layer, and ramp shades), maps each legacy token to a New-set target with a confidence score, then applies non-interactively: mappings whose confidence is ≥ --min-confidence (default 0.7) are auto-accepted, and everything below the threshold is skipped and listed for manual review (never auto-bound). It is additive — the breaking cutover that collapses the deprecated aliases is a separate, opt-in step and is never performed here. When --report is set, the scalable plan stats plus the applied/skipped mappings are merged into the same report file.

CI usage

particles migrate fits a CI/CD pipeline. Authenticate once (the device-auth token is reused), then run non-interactively:

# Token is read from the CLI config (auth.json) written by `particles auth login`,
# or inject PARTICLES_API_URL + a pre-provisioned config in CI.
particles migrate --yes --path ./tokens --project "$PARTICLES_PROJECT_ID" --report migration-report.json

The command exits non-zero on failure (including a plan-gate rejection), so it can gate a pipeline. The Scalability Pass (--scalable) is CI-friendly: under --yes it applies directly (no confirmation), auto-accepting mappings at or above --min-confidence and skipping the rest. If the project's plan is below Business, the pass is skipped with a warning but the file migration still succeeds.

particles token-studio sync

Pull the latest tokens from Studio into your local theme file.

Version resolution order: --version → --branch → latest published release → branch HEAD.

particles token-studio sync [options]

Options:
  --branch <branch>        Sync from a specific branch (default: main)
  --version <semver>       Sync a specific published release
  --wcag-level <level>     Enforce WCAG contrast (AA or AAA)
  --platform-id <uuid>     Platform to sync (multi-level projects only; falls back to config)
  --config <path>          Path to config file

--platform-id is only relevant for multi-level projects with named platforms. Standalone projects omit it and the API behaves identically to before.

particles token-studio export

Export resolved tokens in a specific format to stdout or a file.

particles token-studio export [options]

Options:
  --format <format>        tailwind-v4 | css | scss | style-dictionary | dtcg | json | ts | js
  --branch <branch>        Export from a specific branch
  --version <semver>       Export a specific published release
  --output <path>          Write to file instead of stdout
  --platform-id <uuid>     Platform to export (multi-level projects only; falls back to config)
  --config <path>          Path to config file

# 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

particles token-studio push

Push a local token file into a project branch. Useful for bootstrapping a new project, migrating an existing token library, or scripting bulk token updates from CI.

Requires the tokens:write permission on the project.

particles token-studio push [options]

Options:
  --file <path>            Path to the token file to push (required)
  --branch <branch>        Target branch (default: main)
  --tier <tier>            Default tier for tokens that don't declare one:
                           primitive | semantic | composition  (default: primitive)
  --dry-run                Preview what would change without applying it
  --config <path>          Path to config file

Supported input formats

The format is inferred from the file extension:

| Extension | Detected 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 (same shape; as const and export type are stripped before evaluation) |

CSS and SCSS files are parsed server-side. JS and TS files are evaluated locally in a sandboxed context with a 5-second timeout, then converted to DTCG JSON before upload.

Note: JS/TS composition tokens (values that are plain nested objects) become individual flat leaf tokens after import. Use DTCG JSON (.json) to preserve composition token structure.

Dry-run preview

particles token-studio push --file ./tokens/globals.json --dry-run

Output:

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

Errors

| Error | Cause | | --------------------------------------------- | ------------------------------------------------------------------------- | | Permission denied: tokens:write is required | Your role on this project does not include write access | | Not a member of this organization | The authenticated account has no membership in the project's organization | | File not found | The path passed to --file does not exist |

particles token-studio branch create

Create a new branch forked from an existing one. Requires the branch:create permission (Admin role or Designer with elevated permissions).

particles token-studio branch create <name> [options]

Options:
  --from <branch>          Source branch to fork from (default: main)
  --config <path>          Path to config file

# Create a branch 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

Errors

| Error | Cause | | ---------------------------------------------- | ------------------------------------------ | | Permission denied: branch:create is required | Your role does not include branch creation | | Branch "<name>" not found | The --from branch does not exist |

particles token-studio modules

For a multi-level product that consumes Foundation / Brand modules, inspect linked modules and preview pending updates. Both commands are read-only — accept updates in Particles UI Studio (Project → Token modules).

# List linked modules — pinned release vs latest, and updates available
particles token-studio modules status [--config <path>]

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

Standalone projects have no modules — modules status simply reports that.

Deprecated: particles token-studio foundation sync (the legacy copy/sync foundation model) is superseded by modules. It still runs but prints a deprecation warning.

particles theme

particles theme list                      # List all named themes
particles theme generate <name>           # Generate CSS for a theme
particles theme generate-all              # Generate CSS for all themes

Output formats

| Format | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | tailwind-v4 | CSS custom properties compatible with Tailwind CSS v4 | | css | Plain CSS custom properties | | scss | SCSS variables | | style-dictionary | Style Dictionary JSON | | dtcg | W3C / DTCG Design Tokens format | | json | Raw JSON | | ts | TypeScript theme object with as const + Theme type. Drops into MUI createTheme() or styled-components ThemeProvider | | js | Plain JS theme object — same shape as ts, no type annotations |

TS / JS theme object shape

Tokens are grouped by type (colors, spacing, fontSize, radii, shadows, …) with groupPath nested underneath. Composition tokens are emitted as parsed nested objects. Semantic tokens emit fully resolved values (a snapshot), since JS objects can't reference siblings cleanly.

// src/theme.ts
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 — pass theme straight into ThemeProvider:

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

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

MUI — spread the tokens 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) },
})

Configuration

particles init creates particles-ui.json in the project root:

{
  "organizationId": "your-org-id",
  "projectId": "your-project-id",
  "format": "tailwind-v4",
  "outputDestination": "src/globals.css"
}

For multi-level projects with named platforms, platformId is also persisted so every subsequent sync and export targets the same platform without needing the flag each time:

{
  "organizationId": "your-org-id",
  "projectId": "your-project-id",
  "format": "tailwind-v4",
  "outputDestination": "src/globals.css",
  "platformId": "018fde70-0000-7000-8000-000000000001"
}

Standalone projects omit platformId — all commands work identically without it.

License

MIT