CLI Overview

The Specs command-line interface (CLI) generates design system specifications from Figma REST API data without requiring the Figma Plugin UI. It enables automation, batch processing, and CI/CD integration.

Commands

Command	Purpose	Output
`init`	Initialize config files with defaults	`config/conventions/` (one file per platform), `config/settings.yaml`
`fetch`	Download raw REST payloads from Figma	JSON files in `data.directory`
`scan`	List all components in file	Markdown manifest
`applyCustomTokens`	Inject `$custom` objects into fetched data	Modified variables/styles JSON
`generate`	Generate specs from a manifest or single component	YAML/JSON spec file(s)
`analyze`	Run analyzers over generated specs	Reports in `analysis/`
`migrate`	Convert older workspace layouts to the current one	Rewritten `config/` files
`version`	Version the workspace: diffs, semver bumps, reports, changelogs	`versions/` folders, ledgers, reports
`skills`	Install the premerge and release orchestration skills	Skill files in `.claude/skills/`
`react` (experimental)	Emit the React target	Components, contracts, stylesheets, stories in `react/`
`webcomponents` (experimental)	Emit the Web Components target	Elements, contracts, stylesheets, stories in `webcomponents/`
`bridge` (experimental)	Start/stop/check the local bridge `render` talks to	Background process
`cache` (experimental)	Build the lookup tables `render` resolves specs against	YAML files in `{data.directory}/cache`
`render` (experimental)	Send a spec to the CLI bridge to render it live in Figma	Live Figma component

Global Options

--help - Show command help (all commands)
--version - Show CLI version
--verbose - Enable detailed logging (fetch, scan, generate, react, webcomponents, analyze, render)

Free vs. Pro

Specs CLI works without a license key. At the free tier, specs include full component structure: anatomy, props, variants, and raw style values.

With a Pro license, specs also include design token references, variable bindings, and visibility bindings — connecting your specs directly to your design token system.

Feature	Free	Pro
Anatomy, props, variants	Yes	Yes
Layout and raw style values	Yes	Yes
Design token references	—	Yes
Variable and visibility bindings	—	Yes

Set up your license key in your environment to unlock Pro features. See Getting Started — environment setup and Licensing.

Output Format

The CLI generates the same specification format as the Figma Plugin:

components:
  dsButton:
    title: DS Button
    props:
      size:
        type: variant
        values: [small, medium, large]
      variant:
        type: variant
        values: [primary, secondary]
    anatomy:
      - id: container
        name: Container
        type: FRAME
      - id: label
        name: Label
        type: TEXT
    variants:
      - props:
          size: small
          variant: primary
        anatomy:
          container:
            styles:
              paddingLeft: { value: 12, type: ABSOLUTE }

File Outputs

specs fetch writes deterministic filenames based on your config aliases.

Example (with data.directory: ./data in config/settings.yaml):

data/
├── library.file.json
├── library.variables.json
├── library.styles.json
├── foundations.variables.json
└── foundations.styles.json

generate uses these files by default when data.sources in config/settings.yaml declares the corresponding aliases and fetch kinds.

Requirements

Node.js 18 or higher
Figma access token (for fetch) via FIGMA_TOKEN
Figma REST API data (JSON files from Figma API endpoints, produced by fetch):
- file / styles — any Figma plan with REST API access
- variables — Figma restricts the variables REST endpoints to organizations on an Enterprise plan, regardless of your Specs license; on any other plan, fetch variables through the plugin with --from-bridge
License key (optional) via SPECS_LICENSE_KEY for Pro features
A running CLI bridge and open Figma session (for render only) — see the Render to Figma guide

See Getting Started for installation instructions.