Documentation

CLI Reference

The reframe CLI covers authentication, local iteration, publishing, and consumer-side migration. Most teams start with reframe login and reframe dev. Studio handles automatic publishing on merge, but the full command set is here when you need it.

Terminalbash

npm install -g @reframeui/reframe

Authenticate with your ReframeUI account. Opens a browser OAuth flow and stores the token in ~/.reframe/credentials.

Terminalbash

# Interactive (opens browser)
reframe login

In CI, skip the browser flow by setting REFRAMEUI_API_KEY. The CLI reads it automatically and does not open a browser.

Terminalbash

# CI usage (no browser required)
REFRAMEUI_API_KEY=your_key reframe whoami

reframe logout

Sign out and revoke stored credentials.

Terminalbash

reframe logout

reframe whoami

Prints the currently authenticated account. Useful in CI to confirm the correct token is active before running a publish step.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe whoami
Authenticated as: jane@acme.com (acme / design-system)

Terminalbash

$ reframe whoami --json
{
  "email": "jane@acme.com",
  "workspace": "acme",
  "project": "design-system"
}

reframe dev

Starts a local hot-reload proxy on http://localhost:4242. Token and component changes reflect in Studio preview as you work.

Flagstext

Flags:
  --branch <name>    Branch to watch              [default: main]
  --port <port>      Local port                   [default: 4242]
  --out <dir>        Write token files to a directory and keep them synced

Terminalbash

reframe dev --branch feature/dark-mode --port 3001

Example output:

Terminal outputbash

$ reframe dev --branch feature/dark-mode --port 3001
  Connected to @acme/design-system (feature/dark-mode)
  Token files:   http://localhost:3001/tokens.css
  Components:    http://localhost:3001/design-system.js
  Watching for changes...

reframe publish

Publish a new version of your design system. Reads the bump strategy from reframe.config.json unless overridden. In CI, set REFRAMEUI_API_KEY to authenticate without a browser (same as reframe login). Use --message to attach a release note. Every consumer sees it in their change summary before the update lands.

Flagstext

Usage:
  reframe publish [bump]

Arguments:
  [bump]             Version bump: patch, minor, or major

Flags:
  --bump <bump>      Version bump strategy (overrides reframe.config.json)
  --message <msg>    Release note for this version

Terminalbash

# Interactive (prompts for bump type)
reframe publish

Terminalbash

# Patch release, no prompt
reframe publish --bump patch

Terminalbash

# Patch release with release note
reframe publish --bump patch --message "Tightened spacing scale, updated brand tokens"

Example GitHub Actions workflow:

.github/workflows/publish.ymlyaml

name: Publish design system

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install reframe
        run: npm install -g @reframeui/reframe

      - name: Publish design system
        run: reframe publish --bump patch
        env:
          REFRAMEUI_API_KEY: ${{ secrets.REFRAMEUI_API_KEY }}

reframe pull

Download the generated source files for a branch to disk.

Flagstext

Flags:
  --branch <name>    Branch to pull    [default: main]
  --out <dir>        Output directory  [default: ./design-system]

Terminalbash

$ reframe pull --branch main
  Pulling @acme/design-system (main)...
  design-system/
    tokens.css
    tokens.js
    tokens.d.ts
    components.js
    components.d.ts
  Done.

reframe status

Show the connection status for the current project and branch.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe status
  Project:     acme/design-system
  Branch:      main
  Published:   2026-03-28
  Connection:  Connected

Terminalbash

$ reframe status --json
{
  "project": "acme/design-system",
  "branch": "main",
  "lastPublished": "2026-03-28",
  "connected": true
}

reframe branches

List all branches for the current project.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe branches
  * main              (published 2026-03-28)
    feature/dark-mode
    fix/spacing-tokens

Terminalbash

$ reframe branches --json
[
  { "name": "main", "lastPublished": "2026-03-28", "current": true },
  { "name": "feature/dark-mode", "lastPublished": null, "current": false },
  { "name": "fix/spacing-tokens", "lastPublished": null, "current": false }
]

reframe init

Scaffold a consumer project. Without --ci, the command prompts interactively. With --ci, it generates a GitHub Actions workflow without any prompts. Use --ci in automated environments to skip all prompts.

Flagstext

Flags:
  --ci    Generate a GitHub Actions workflow without interactive prompts

Terminalbash

$ reframe init
  ? Workspace slug: acme
  ? Design system slug: design-system
  Created reframe.config.json
  Created .github/workflows/reframe-sync.yml

reframe open

Open the current project in Studio in your browser.

Terminalbash

$ reframe open
  Opening acme/design-system in Studio...

reframe diff

Show token changes between two published versions. Defaults to comparing the previous and latest published versions.

Flagstext

Flags:
  --from <version>    Starting version  [default: previous published]
  --to <version>      Ending version    [default: latest published]

Terminalbash

$ reframe diff --from 1.4.0 --to 1.5.0
  color.brand.primary    #0047FF  ->  #0052FF
  color.surface.raised   #1A1A2E  ->  #16213E
  spacing.md             16px     ->  18px
  3 tokens changed

reframe lint

Scan source files for hardcoded design values that have a matching token. Reports file and line number for each violation.

Flagstext

Flags:
  --dir <path>     Directory to scan   [default: ./src]
  --ext <list>     File extensions     [default: ts,tsx,js,jsx,css,scss]
  --json           Print results as JSON instead of plain text

Terminalbash

$ reframe lint
  src/components/Button.tsx:24    color: #0047FF   (use color.brand.primary)
  src/styles/globals.css:8        font-size: 16px  (use typography.body.size)
  2 violations found

reframe tokens export

Export your design system tokens to a file.

Flagstext

Flags:
  --format <format>  Output format   [default: dtcg]
                     Values: dtcg, css, js, ts, scss, style_dictionary
  --output <file>    Output file     [default: tokens.json]
  --mode <mode>      Token mode      [default: all]
                     Values: all, light-only, dark-only

Terminalbash

# Export as DTCG JSON (default)
reframe tokens export

Terminalbash

# Export as CSS custom properties, light mode only
reframe tokens export --format css --output tokens.css --mode light-only

reframe upgrade

Migrate your source files to a target version. Finds renamed or removed tokens and updates references in place. Use --auto-apply --yes in CI to apply all renames without prompts.

Flagstext

Flags:
  --to <version>     Target version (required)
  --dir <path>       Directory to scan   [default: ./src]
  --ext <list>       File extensions     [default: ts,tsx,js,jsx,css,scss]
  --auto-apply       Apply all renames without prompts
  --yes              Skip the breaking-change confirmation gate

Terminalbash

# Interactive migration
reframe upgrade --to 2.0.0

Terminalbash

# CI migration, no prompts
reframe upgrade --to 2.0.0 --auto-apply --yes

Example output:

Terminal outputbash

$ reframe upgrade --to 2.0.0 --auto-apply --yes
  Scanning ./src...
  Renamed: color.brand        ->  color.brand.primary  (14 files)
  Removed: spacing.xl (no replacement)                 (3 files)
  Done. Review changes before committing.

reframe completion

Generate a shell completion script for bash or zsh. If --shell is omitted, the shell is auto-detected from $SHELL.

Flagstext

Flags:
  --shell <shell>    Shell to generate for: bash or zsh  [default: auto-detected from $SHELL]

Terminalbash

# Add completions to zsh
reframe completion --shell zsh >> ~/.zshrc

Next steps

Learn how to sync your tokens with Figma.

Figma Plugin →

Documentation

CLI Reference

Terminalbash

npm install -g @reframeui/reframe

Authenticate with your ReframeUI account. Opens a browser OAuth flow and stores the token in ~/.reframe/credentials.

Terminalbash

# Interactive (opens browser)
reframe login

In CI, skip the browser flow by setting REFRAMEUI_API_KEY. The CLI reads it automatically and does not open a browser.

Terminalbash

# CI usage (no browser required)
REFRAMEUI_API_KEY=your_key reframe whoami

reframe logout

Sign out and revoke stored credentials.

Terminalbash

reframe logout

reframe whoami

Prints the currently authenticated account. Useful in CI to confirm the correct token is active before running a publish step.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe whoami
Authenticated as: jane@acme.com (acme / design-system)

Terminalbash

$ reframe whoami --json
{
  "email": "jane@acme.com",
  "workspace": "acme",
  "project": "design-system"
}

reframe dev

Starts a local hot-reload proxy on http://localhost:4242. Token and component changes reflect in Studio preview as you work.

Flagstext

Flags:
  --branch <name>    Branch to watch              [default: main]
  --port <port>      Local port                   [default: 4242]
  --out <dir>        Write token files to a directory and keep them synced

Terminalbash

reframe dev --branch feature/dark-mode --port 3001

Example output:

Terminal outputbash

$ reframe dev --branch feature/dark-mode --port 3001
  Connected to @acme/design-system (feature/dark-mode)
  Token files:   http://localhost:3001/tokens.css
  Components:    http://localhost:3001/design-system.js
  Watching for changes...

reframe publish

Flagstext

Usage:
  reframe publish [bump]

Arguments:
  [bump]             Version bump: patch, minor, or major

Flags:
  --bump <bump>      Version bump strategy (overrides reframe.config.json)
  --message <msg>    Release note for this version

Terminalbash

# Interactive (prompts for bump type)
reframe publish

Terminalbash

# Patch release, no prompt
reframe publish --bump patch

Terminalbash

# Patch release with release note
reframe publish --bump patch --message "Tightened spacing scale, updated brand tokens"

Example GitHub Actions workflow:

.github/workflows/publish.ymlyaml

name: Publish design system

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install reframe
        run: npm install -g @reframeui/reframe

      - name: Publish design system
        run: reframe publish --bump patch
        env:
          REFRAMEUI_API_KEY: ${{ secrets.REFRAMEUI_API_KEY }}

reframe pull

Download the generated source files for a branch to disk.

Flagstext

Flags:
  --branch <name>    Branch to pull    [default: main]
  --out <dir>        Output directory  [default: ./design-system]

Terminalbash

$ reframe pull --branch main
  Pulling @acme/design-system (main)...
  design-system/
    tokens.css
    tokens.js
    tokens.d.ts
    components.js
    components.d.ts
  Done.

reframe status

Show the connection status for the current project and branch.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe status
  Project:     acme/design-system
  Branch:      main
  Published:   2026-03-28
  Connection:  Connected

Terminalbash

$ reframe status --json
{
  "project": "acme/design-system",
  "branch": "main",
  "lastPublished": "2026-03-28",
  "connected": true
}

reframe branches

List all branches for the current project.

Flagstext

Flags:
  --json    Print result as JSON instead of plain text

Terminalbash

$ reframe branches
  * main              (published 2026-03-28)
    feature/dark-mode
    fix/spacing-tokens

Terminalbash

$ reframe branches --json
[
  { "name": "main", "lastPublished": "2026-03-28", "current": true },
  { "name": "feature/dark-mode", "lastPublished": null, "current": false },
  { "name": "fix/spacing-tokens", "lastPublished": null, "current": false }
]

reframe init

Flagstext

Flags:
  --ci    Generate a GitHub Actions workflow without interactive prompts

Terminalbash

$ reframe init
  ? Workspace slug: acme
  ? Design system slug: design-system
  Created reframe.config.json
  Created .github/workflows/reframe-sync.yml

reframe open

Open the current project in Studio in your browser.

Terminalbash

$ reframe open
  Opening acme/design-system in Studio...

reframe diff

Show token changes between two published versions. Defaults to comparing the previous and latest published versions.

Flagstext

Flags:
  --from <version>    Starting version  [default: previous published]
  --to <version>      Ending version    [default: latest published]

Terminalbash

$ reframe diff --from 1.4.0 --to 1.5.0
  color.brand.primary    #0047FF  ->  #0052FF
  color.surface.raised   #1A1A2E  ->  #16213E
  spacing.md             16px     ->  18px
  3 tokens changed

reframe lint

Scan source files for hardcoded design values that have a matching token. Reports file and line number for each violation.

Flagstext

Flags:
  --dir <path>     Directory to scan   [default: ./src]
  --ext <list>     File extensions     [default: ts,tsx,js,jsx,css,scss]
  --json           Print results as JSON instead of plain text

Terminalbash

$ reframe lint
  src/components/Button.tsx:24    color: #0047FF   (use color.brand.primary)
  src/styles/globals.css:8        font-size: 16px  (use typography.body.size)
  2 violations found

reframe tokens export

Export your design system tokens to a file.

Flagstext

Flags:
  --format <format>  Output format   [default: dtcg]
                     Values: dtcg, css, js, ts, scss, style_dictionary
  --output <file>    Output file     [default: tokens.json]
  --mode <mode>      Token mode      [default: all]
                     Values: all, light-only, dark-only

Terminalbash

# Export as DTCG JSON (default)
reframe tokens export

Terminalbash

# Export as CSS custom properties, light mode only
reframe tokens export --format css --output tokens.css --mode light-only

reframe upgrade

Migrate your source files to a target version. Finds renamed or removed tokens and updates references in place. Use --auto-apply --yes in CI to apply all renames without prompts.

Flagstext

Flags:
  --to <version>     Target version (required)
  --dir <path>       Directory to scan   [default: ./src]
  --ext <list>       File extensions     [default: ts,tsx,js,jsx,css,scss]
  --auto-apply       Apply all renames without prompts
  --yes              Skip the breaking-change confirmation gate

Terminalbash

# Interactive migration
reframe upgrade --to 2.0.0

Terminalbash

# CI migration, no prompts
reframe upgrade --to 2.0.0 --auto-apply --yes

Example output:

Terminal outputbash

$ reframe upgrade --to 2.0.0 --auto-apply --yes
  Scanning ./src...
  Renamed: color.brand        ->  color.brand.primary  (14 files)
  Removed: spacing.xl (no replacement)                 (3 files)
  Done. Review changes before committing.

reframe completion

Generate a shell completion script for bash or zsh. If --shell is omitted, the shell is auto-detected from $SHELL.

Flagstext

Flags:
  --shell <shell>    Shell to generate for: bash or zsh  [default: auto-detected from $SHELL]

Terminalbash

# Add completions to zsh
reframe completion --shell zsh >> ~/.zshrc

Next steps

Learn how to sync your tokens with Figma.

Figma Plugin →