Tooling

CLI Reference

Use the Styleframe CLI to initialize projects and build optimized CSS from your configuration files.

Overview

The Styleframe CLI is a command-line interface that helps you initialize new projects and build production-ready CSS from your Styleframe configuration. It provides a streamlined workflow from project setup to optimized style generation.

Why use the CLI?

The CLI helps you:

  • Quick project setup: Initialize Styleframe configuration and dependencies with a single command.
  • Optimized builds: Generate production-ready CSS from your configuration files.
  • Flexible output: Control where and how your styles are generated.
  • Consistent workflow: Integrate Styleframe into your development and deployment pipelines.

Installation

Install the CLI as a development dependency:

pnpm install -g styleframe

Commands

The CLI provides five primary commands: init for project setup, build for generating CSS output, check for finding problems without building, inspect for listing what your configuration registers, and dtcg for exporting and importing design tokens in DTCG format.


init

command
styleframe init [options]
Initialize a new Styleframe project in your current directory.

Options

OptionAliasTypeDefaultDescription
--cwd-d, --dirstringprocess.cwd()Directory where the project will be initialized

Usage

styleframe init
  1. Creates a styleframe.config.ts file with basic configuration
  2. Creates or updates tsconfig.json with styleframe includes
  3. Adds all styleframe packages to your package.json dependencies
  4. Detects and configures your framework (Vite or Nuxt), if applicable
  5. Skips creating files that already exist (won't overwrite existing config)
Pro tip: After running init, don't forget to run npm install to install the added dependencies.

build

command
styleframe build [entry] [options]
Build your Styleframe project and generate CSS output files.

Options

OptionAliasTypeDefaultDescription
entry-stringstyleframe.config.tsEntry point file(s) for the build
--outputDir-o, --outstringstyleframeOutput directory for built files
--clean-booleanfalseClean output directory before build

Usage

styleframe build
  1. Loads your Styleframe configuration from the entry file
  2. Processes all styles, variables, themes, and utilities
  3. Generates optimized CSS files in the specified output directory

The build command generates a structured output directory:

styleframe/
├── index.css          # Main compiled CSS
└── index.ts           # Main compiled TypeScript

Warnings and exit codes

Before it writes anything, the build checks your configuration with validate() and prints one warning line for each problem it finds: the code, where you made the mistake and what's wrong, with the closest token name when there is one.

WARN  unresolved-reference recipe "button" › base › background: Reference "@color.brnad" resolves to no variable. Did you mean "@color.brand"?

The exit code tells a script or an agent whether the build worked, so you can trust it in CI:

Exit codeWhen
0The build wrote its files. Warnings don't change this, unless strict is on.
1The build failed, like when the output directory can't be written, or your instance sets strict: true and the check found a problem. Under strict, nothing is written.

check

command
styleframe check [entry] [options]
Check your Styleframe configuration for problems without building it or writing any files.

Options

OptionAliasTypeDefaultDescription
entry-stringstyleframe.config.tsEntry point file to check
--json-booleanfalsePrint the result as one JSON document on stdout
--typecheck-booleanfalseAlso type-check the entry file with your project's TypeScript

Usage

styleframe check
  1. Loads your Styleframe configuration from the entry file
  2. Runs validate() on it and prints one warning line per problem
  3. Exits with 0 when it finds no problem and 1 when it finds any, whether or not strict is on

When the entry file doesn't exist, check prints Config file not found on stderr and exits with 1, so a mistyped path never passes as a clean config.

With --json, the command prints one document on stdout and nothing else, so an agent or a script can parse it directly. When the config file is missing or fails to load, it prints the error on stderr instead, nothing on stdout, and exits with 1.

{
  "ok": false,
  "diagnostics": [
    {
      "code": "unresolved-reference",
      "severity": "warning",
      "message": "Reference \"@color.brnad\" resolves to no variable. Did you mean \"@color.brand\"?",
      "path": "recipe \"button\" › base › background",
      "suggestion": "color.brand"
    }
  ]
}

Each diagnostic has a stable code (unresolved-reference, undefined-theme-override or duplicate-variable), a severity that's error under strict and warning otherwise, a message, the path to where the problem was made and a suggestion when a registered token name is within two edits.

Type checking

The --typecheck flag also runs TypeScript on your entry file, so a typo like a default variant that isn't one of the recipe's options shows up in the same call as the problems validate() finds. It uses the tsc that your project installs and the compiler options of the tsconfig.json nearest to the entry file, or strict defaults when there's none. Only the entry file and the files it imports are checked, not the rest of your project.

To run tsc on that one file, the command writes a temporary tsconfig into your project's node_modules/.cache and removes it when it's done. That way your types and @types packages resolve as they do for your project. When node_modules is read-only, like under Nix, it uses your system's temporary directory instead. It turns off incremental for the run, and composite too, with declaration left on, so your .tsbuildinfo and output directory stay as they are.

Each type error becomes a diagnostic with the code typescript, the severity error, its TS number at the start of the message and the file and line as its path:

{
  "code": "typescript",
  "severity": "error",
  "message": "TS2322: Type '\"medium\"' is not assignable to type '\"md\" | \"sm\" | undefined'.",
  "path": "styleframe.config.ts:4"
}

The CLI doesn't bundle TypeScript, since it's an optional peer dependency. When your project doesn't install typescript, check --typecheck prints TypeScript not found on stderr and exits with 1.

Pro tip: Run styleframe check --json after every change an agent makes to your configuration. It writes no files and reports every problem in one pass.

inspect

command
styleframe inspect [entry] [section] [options]
List the variables, themes, utilities, modifiers and recipes your configuration registers, without building it or reading its CSS.

Options

OptionAliasTypeDefaultDescription
entry-stringstyleframe.config.tsEntry point file to inspect
section-string-One section to print: variables, themes, utilities, modifiers or recipes
--json-booleanfalsePrint the result as one JSON document on stdout

Usage

styleframe inspect

The command prints the snapshot that inspect() returns, with one list per section:

variables (1)
  color.brand  --color--brand: #6366f1

themes (1)
  dark  .dark-theme, [data-theme="dark"]
    color.brand: #818cf8

utilities (1)
  background-color
    values: brand
    modifiers: hover
    classes: _background-color:brand _hover:background-color:brand

modifiers (1)
  hover

recipes (1)
  button
    size: sm, md (default: md)

With --json, it prints one document on stdout and nothing else: the whole snapshot, or an object with only the section you asked for, like { "themes": [...] }. When you pass a section name on its own, like styleframe inspect themes, the command reads it as the section and inspects styleframe.config.ts. An unknown section or a missing config file prints an error on stderr and exits with 1.

Pro tip: Run styleframe inspect --json before an agent edits your configuration. It shows the token names, the themes a preset adds, the class names a utility emits and each recipe's variant options, so the agent doesn't have to read the source or the generated CSS.

watch 🚧

command
styleframe watch [entry] [options]
Watch mode is planned for a future release. It will automatically rebuild your styles when configuration files change.
Coming soon: Track progress in the GitHub repository.

dtcg

command
styleframe dtcg <subcommand> [options]
Export Styleframe variables to and import them from spec-conformant DTCG (Design Tokens Community Group) JSON. The export output is consumed by the @styleframe/figma plugin (which performs the DTCG → Figma value conversion) and any other DTCG-compatible tooling; the import command generates Styleframe TypeScript code from a DTCG JSON file.

dtcg export

command
styleframe dtcg export [options]
Export Styleframe variables to DTCG format JSON.
Options
OptionAliasTypeDefaultDescription
--config-cstringstyleframe.config.tsPath to the Styleframe config file
--output-ostring.Output directory for DTCG files
--collection-n, --namestringDesign TokensCollection name embedded in the export
Usage
styleframe dtcg export

dtcg import

command
styleframe dtcg import [options]
Generate Styleframe TypeScript code from DTCG format JSON (e.g. produced by the @styleframe/figma plugin's Export action or the Variables REST API).
Options
OptionAliasTypeDefaultDescription
--input-istring-Input DTCG JSON file or directory containing tokens.json (required)
--output-ostringtokens.styleframe.tsOutput Styleframe TypeScript file path
--composables-booleantrueUse @styleframe/theme composables (useColorDesignTokens, useSpacingDesignTokens, etc.)
--rem-booleanfalseUse rem units for dimensions instead of px
--baseFontSize-string16Base font size for rem conversion (in pixels)
--instanceName-stringsName for the Styleframe instance variable
Usage
styleframe dtcg import -i tokens/
  1. Reads tokens.json from the input path (or a single file); auto-detects a sibling tokens.resolver.json for multi-mode support
  2. Converts DTCG format to Styleframe variables and themes
  3. Generates TypeScript code with proper imports and variable definitions
  4. Optionally uses @styleframe/theme composables for common patterns

figma

command
styleframe figma <subcommand> [options]
Export and import Figma-compatible DTCG per-mode files. Unlike the spec-conformant dtcg commands, figma uses only the three types Figma supports (number, color, string), flattens structured values to primitives, and writes one complete .tokens.json file per mode — ready for direct import into Figma via the Styleframe Figma Plugin.

figma export

command
styleframe figma export [options]
Export Styleframe variables to Figma-compatible DTCG per-mode files.
Options
OptionAliasTypeDefaultDescription
--config-cstringstyleframe.config.tsPath to the Styleframe config file
--output-ostring.Output directory for per-mode .tokens.json files
--collection-n, --namestringDesign TokensCollection name embedded in the export
Usage
styleframe figma export
  1. Loads your Styleframe config and builds a spec-conformant DTCG document
  2. Flattens rich DTCG types to Figma's model (dimension → number, cubicBezier → string, etc.)
  3. Clamps colour components to the [0, 1] range and forces sRGB
  4. Writes one complete {ModeName}.tokens.json per mode (e.g. Default.tokens.json, Dark.tokens.json)
The Figma export is a one-way simplification layer on top of the rich dtcg export. For spec-conformant DTCG output (e.g. for Style Dictionary or Tokens Studio), use styleframe dtcg export instead.

figma import

command
styleframe figma import [options]
Generate Styleframe TypeScript code from Figma-compatible DTCG per-mode files. Accepts a single .tokens.json file or a directory of per-mode files.
Options
OptionAliasTypeDefaultDescription
--input-istring-Input .tokens.json file or directory of per-mode files (required)
--output-ostringtokens.styleframe.tsOutput Styleframe TypeScript file path
--composables-booleantrueUse @styleframe/theme composables (useColorDesignTokens, useSpacingDesignTokens, etc.)
--rem-booleanfalseUse rem units for dimensions instead of px
--baseFontSize-string16Base font size for rem conversion (in pixels)
--instanceName-stringsName for the Styleframe instance variable
Usage
styleframe figma import -i tokens/
  1. Reads all .tokens.json files from the input path (or a single file)
  2. Extracts the mode name from $extensions["com.figma.modeName"] or the filename
  3. Merges per-mode documents into a multi-mode token set
  4. Generates Styleframe TypeScript code with variables and themes

Best Practices

  • Use npm scripts: Define CLI commands in your package.json for consistent execution across your team.
  • Version control configs: Commit your styleframe.config.ts to ensure consistent styling across environments.
  • Integrate with CI/CD: Run styleframe check and styleframe build in your deployment pipeline. Both exit with 1 when they fail, so the pipeline stops.
  • Organize output: Use --outputDir to organize generated files according to your project structure.
  • Descriptive naming: Use clear names for multiple configs like styleframe.theme.config.ts or styleframe.components.config.ts.
Use native integrations: We recommend using native integrations with Vite and other tools for building projects using styleframe.

FAQ