CLI Reference
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
yarn add -g styleframe
npm install -g styleframe
bun add -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
styleframe init [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--cwd | -d, --dir | string | process.cwd() | Directory where the project will be initialized |
Usage
styleframe init
styleframe init --cwd ./my-project
styleframe init -d ./my-project
- Creates a
styleframe.config.tsfile with basic configuration - Creates or updates
tsconfig.jsonwith styleframe includes - Adds all
styleframepackages to yourpackage.jsondependencies - Detects and configures your framework (Vite or Nuxt), if applicable
- Skips creating files that already exist (won't overwrite existing config)
init, don't forget to run npm install to install the added dependencies.build
styleframe build [entry] [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
entry | - | string | styleframe.config.ts | Entry point file(s) for the build |
--outputDir | -o, --out | string | styleframe | Output directory for built files |
--clean | - | boolean | false | Clean output directory before build |
Usage
styleframe build
styleframe build my-styles.config.ts
styleframe build --outputDir dist/styles
styleframe build -o dist/styles
styleframe build --out dist/styles
- Loads your Styleframe configuration from the entry file
- Processes all styles, variables, themes, and utilities
- 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 code | When |
|---|---|
0 | The build wrote its files. Warnings don't change this, unless strict is on. |
1 | The 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
styleframe check [entry] [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
entry | - | string | styleframe.config.ts | Entry point file to check |
--json | - | boolean | false | Print the result as one JSON document on stdout |
--typecheck | - | boolean | false | Also type-check the entry file with your project's TypeScript |
Usage
styleframe check
styleframe check --json
styleframe check --typecheck --json
- Loads your Styleframe configuration from the entry file
- Runs
validate()on it and prints one warning line per problem - Exits with
0when it finds no problem and1when it finds any, whether or notstrictis 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.
styleframe check --json after every change an agent makes to your configuration. It writes no files and reports every problem in one pass.inspect
styleframe inspect [entry] [section] [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
entry | - | string | styleframe.config.ts | Entry point file to inspect |
section | - | string | - | One section to print: variables, themes, utilities, modifiers or recipes |
--json | - | boolean | false | Print the result as one JSON document on stdout |
Usage
styleframe inspect
styleframe inspect styleframe.config.ts themes
styleframe inspect themes
styleframe inspect --json
styleframe inspect recipes --json
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.
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 🚧
styleframe watch [entry] [options]
dtcg
styleframe dtcg <subcommand> [options]
@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
styleframe dtcg export [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--config | -c | string | styleframe.config.ts | Path to the Styleframe config file |
--output | -o | string | . | Output directory for DTCG files |
--collection | -n, --name | string | Design Tokens | Collection name embedded in the export |
Usage
styleframe dtcg export
styleframe dtcg export --output tokens/
styleframe dtcg export -o tokens/
styleframe dtcg export --config src/styleframe.config.ts
styleframe dtcg export -c src/styleframe.config.ts
styleframe dtcg export --collection "My Design System"
styleframe dtcg export -n "My Design System"
dtcg import
styleframe dtcg import [options]
@styleframe/figma plugin's Export action or the Variables REST API).Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--input | -i | string | - | Input DTCG JSON file or directory containing tokens.json (required) |
--output | -o | string | tokens.styleframe.ts | Output Styleframe TypeScript file path |
--composables | - | boolean | true | Use @styleframe/theme composables (useColorDesignTokens, useSpacingDesignTokens, etc.) |
--rem | - | boolean | false | Use rem units for dimensions instead of px |
--baseFontSize | - | string | 16 | Base font size for rem conversion (in pixels) |
--instanceName | - | string | s | Name for the Styleframe instance variable |
Usage
styleframe dtcg import -i tokens/
styleframe dtcg import -i tokens.json
styleframe dtcg import -i tokens/ --output src/tokens.styleframe.ts
styleframe dtcg import -i tokens/ -o src/tokens.styleframe.ts
styleframe dtcg import -i tokens/ --rem
styleframe dtcg import -i tokens/ --rem --baseFontSize 14
styleframe dtcg import -i tokens/ --composables false
- Reads
tokens.jsonfrom the input path (or a single file); auto-detects a siblingtokens.resolver.jsonfor multi-mode support - Converts DTCG format to Styleframe variables and themes
- Generates TypeScript code with proper imports and variable definitions
- Optionally uses @styleframe/theme composables for common patterns
figma
styleframe figma <subcommand> [options]
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
styleframe figma export [options]
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--config | -c | string | styleframe.config.ts | Path to the Styleframe config file |
--output | -o | string | . | Output directory for per-mode .tokens.json files |
--collection | -n, --name | string | Design Tokens | Collection name embedded in the export |
Usage
styleframe figma export
styleframe figma export --output tokens/
styleframe figma export -o tokens/
styleframe figma export --collection "My Design System"
styleframe figma export -n "My Design System"
- Loads your Styleframe config and builds a spec-conformant DTCG document
- Flattens rich DTCG types to Figma's model (
dimension→number,cubicBezier→string, etc.) - Clamps colour components to the
[0, 1]range and forces sRGB - Writes one complete
{ModeName}.tokens.jsonper mode (e.g.Default.tokens.json,Dark.tokens.json)
dtcg export. For spec-conformant DTCG output (e.g. for Style Dictionary or Tokens Studio), use styleframe dtcg export instead.figma import
styleframe figma import [options]
.tokens.json file or a directory of per-mode files.Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--input | -i | string | - | Input .tokens.json file or directory of per-mode files (required) |
--output | -o | string | tokens.styleframe.ts | Output Styleframe TypeScript file path |
--composables | - | boolean | true | Use @styleframe/theme composables (useColorDesignTokens, useSpacingDesignTokens, etc.) |
--rem | - | boolean | false | Use rem units for dimensions instead of px |
--baseFontSize | - | string | 16 | Base font size for rem conversion (in pixels) |
--instanceName | - | string | s | Name for the Styleframe instance variable |
Usage
styleframe figma import -i tokens/
styleframe figma import -i Default.tokens.json
styleframe figma import -i tokens/ --rem
styleframe figma import -i tokens/ --rem --baseFontSize 14
styleframe figma import -i tokens/ --composables false
- Reads all
.tokens.jsonfiles from the input path (or a single file) - Extracts the mode name from
$extensions["com.figma.modeName"]or the filename - Merges per-mode documents into a multi-mode token set
- Generates Styleframe TypeScript code with variables and themes
Best Practices
- Use npm scripts: Define CLI commands in your
package.jsonfor consistent execution across your team. - Version control configs: Commit your
styleframe.config.tsto ensure consistent styling across environments. - Integrate with CI/CD: Run
styleframe checkandstyleframe buildin your deployment pipeline. Both exit with1when they fail, so the pipeline stops. - Organize output: Use
--outputDirto organize generated files according to your project structure. - Descriptive naming: Use clear names for multiple configs like
styleframe.theme.config.tsorstyleframe.components.config.ts.
FAQ
Ensure styleframe is present in your node_modules/.bin directory. Alternatively, try running the command with npx:
npx styleframe init
The CLI looks for styleframe.config.ts by default. Either create this file or specify your config path:
styleframe build path/to/your/config.ts
.ts). You can still write your application code in JavaScript while using TypeScript only for the config file.Run the build command with different entry points and output directories:
styleframe build styleframe.theme.config.ts -o dist/theme
styleframe build styleframe.components.config.ts -o dist/components
styleframe.config.ts file using the styleframe() function. The CLI respects all configuration options you set there.build and loadConfiguration functions directly from @styleframe/loader in Node.js scripts.The dtcg command handles both directions:
- Code → Figma: Run
styleframe dtcg exportto generate spec-conformant DTCG JSON files, then import them into Figma using the@styleframe/figmaplugin - Figma → Code: Export your Figma variables as DTCG JSON via the plugin, then run
styleframe dtcg import -i tokens/to generate Styleframe code
# Export Styleframe → DTCG JSON (importable by the Figma plugin)
styleframe dtcg export -o tokens/
# Import Figma → Styleframe
styleframe dtcg import -i tokens/ -o src/tokens.styleframe.ts