@particlesui/cli

Command-line interface for Particles UI — sync design tokens from Particles 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 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 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