CLI

Figmage ships a single command line tool, figmage, with two commands:

• sync — read your Figma library and generate design token files.
• spritesheet — bundle local SVG files into a single sprite sheet.

figmage <command> [options]

Global options

These flags work with any command:

Flag	Description
-h, --help	Show help.
-v, --version	Show the installed Figmage version.
-V, --verbose	Enable verbose logging for API, config, and filtering issues.

sync

Reads your published Figma library and writes design token files to disk based on your config.

figmage sync [options]

Options

Flag	Default	Description
-c, --config <path>	figmage.config.js	Path to the config file.
--only <names>	none	Comma-separated token names to sync, e.g. colors,typography. Everything else is skipped.
--skip <names>	none	Comma-separated token names to exclude, e.g. icons,assets. Everything else is synced.
--on-success <command>	none	Shell command to run after sync completes successfully.

--only and --skip are mutually exclusive — pass at most one of them.

Examples

# Sync every token defined in the config
figmage sync

# Use a custom config path
figmage sync -c ./configs/figmage.config.js

# Sync just a subset
figmage sync --only=colors,icons

# Sync everything except a subset
figmage sync --skip=assets

# Run another command after a successful sync
figmage sync --on-success "npm run build"

# Verbose output for debugging
figmage sync --verbose

Running a command after sync

Use --on-success when another local step should run only after Figmage has successfully finished syncing, such as formatting generated files, building your package, or running tests.

figmage sync --on-success "npm run format:fix"

The command runs through your shell from the current working directory and inherits terminal output. If the command exits with a non-zero status, figmage sync exits as failed.

Filtering with --only and --skip

By default figmage sync processes every token in your config. When you only need to refresh part of your design system, use --only or --skip to narrow the run. Both accept a comma-separated list of token names (the name field of each entry in your tokens array).

How the values are parsed:

1. Split by comma, trimmed of whitespace, and de-duplicated.
2. Empty input (e.g. --only=) is treated as invalid and fails the command.
3. --only and --skip cannot be used together.

Good practices:

1. Keep token names stable in config so partial syncs stay predictable.
2. Use focused, descriptive names like icons and spacing rather than generic ones.
3. Reach for --only in CI jobs that intentionally refresh a single token group (for example, a pipeline that re-exports icons whenever the icon frame changes).

Validation behavior

• Fails if accessToken or fileId is missing from the resolved config.
• Fails if --only or --skip is provided but contains no valid names.
• Fails if both --only and --skip are provided at the same time.

For setup and sync failures, see Troubleshooting.

spritesheet

Bundles a folder of existing SVG files into a single SVG sprite sheet. Use it when your icons already live in your repo as SVG files rather than in Figma. (To build a sprite directly from Figma components, use the imageSprite token type instead.)

figmage spritesheet [options]

Required options

Flag	Description
--sprite-input <path>	Directory containing source SVG files.
--sprite-output <path>	Directory where the generated sprite SVG is written.
--sprite-filename <name>	Output file name without extension.

Optional options

Flag	Default	Description
--sprite-case <case>	kebab	Symbol ID casing: `camel
--sprite-convert-colors	true	Convert hard-coded SVG colors to currentColor.
--sprite-ids-enabled	false	Also generate a file containing the icon IDs.
--sprite-ids-output <path>	sprite output directory	Directory for the IDs file.
--sprite-ids-filename <name>	<sprite-filename>-ids	IDs file name without extension.
--sprite-ids-filetype <type>	ts	IDs file type: `ts

Example

figmage spritesheet \
  --sprite-input ./icons \
  --sprite-output ./public \
  --sprite-filename icon-sprite \
  --sprite-ids-enabled \
  --sprite-ids-output ./src/tokens \
  --sprite-ids-filename icon-sprite-ids \
  --sprite-ids-filetype ts

Given an ./icons directory of .svg files, this writes ./public/icon-sprite.svg and a typed ./src/tokens/icon-sprite-ids.ts listing every icon ID in the sprite.