Zeytal CLI

Learn how to use the Zeytal command-line interface (CLI) to extract data from your Figma files and auto-generate front-end code.

With the CLI package, you can interact with the Zeytal dashboard and your Figma files using a terminal or an automated system.

It enables you to:

  • Extract and optimize your SVGs
  • Extract and translate your Figma styles and variables into various code languages like CSS, TS, SCSS, JSON, etc.

Installing Zeytal CLI

To download and install the Zeytal CLI package, run one of the following commands:

terminal

$
pnpm i -D zeytal

Updating Zeytal CLI

When there is a new release of Zeytal CLI, running any command will show you a message letting you know an update is available.

The easiest way to update it is by running the installation command yet again:

terminal

$
pnpm i -D zeytal@latest

Canary version

To update to the latest canary version run the following command:

terminal

$
pnpm i -D zeytal@canary

Checking the version

The --version option, shorthand -v, can be used to verify the version of Zeytal CLI currently being used.

terminal

$
pnpm zeytal --version

Project authentication

Zeytal CLI doesn’t require you to log in using a CLI command in any way before performing a task.

You must simply pass your Zeytal project’s secret token as an environment variable. Once set up, you can perform any task you want with the CLI. It will recognize your project secret token and perform your tasks using the context of this specific project.

You’ll find your project secret token in the overview and settings tabs of your project’s dashboard.

Zeytal has built-in support for loading environment variables from your .env file.

So, you can paste your project secret token into your .env file like this:

.env

ZEYTAL_PROJECT_TOKEN=ABCDEFGHIJKlmnopqrstuvwxyz123456789

Using in a CI/CD environment

Since you already don’t need a manual input to log in with zeytal in your terminal environment, working with CI/CD environments will work pretty much the same way.

Simply store your project secret token as an environment variable in your favorite CI/CD tool config, then use the CLI commands like you always do.

CI/CD warning

Zeytal works in CI/CD environments, but we recommend caution.

Excessive usage — such as triggering too many API requests — can quickly reach rate limits. This will cause Zeytal commands to fail, which may break parts of your front-end that depend on generated code.

The recommended workflow is to run Zeytal commands locally, commit the output, and push it to your repository.

If you choose to use Zeytal in CI, make sure it’s used sparingly. Only generate code when absolutely necessary.

Note:

API limits adjust dynamically. The more users overload the system, the stricter the limits become.

Generation directory

A new .zeytal directory will be added to your CWD when using a CLI command. The .zeytal dir contains the code generated by your CLI commands for your Zeytal project.

Inside this directory, you’ll find 3 sub-directories:

  • assets
  • styles
  • variables

Each of those 3 dirs can be moved to others places inside your project’s root dir if you need to.

You will have to specify a new path for them in your CLI config file.

Running a CLI command clears the content of the .zeytal/assets, .zeytal/styles, and .zeytal/variables directories. If you don’t want to lose code, don’t add code manually in there.

Zeytal CLI global options

Global options are commonly available to use with multiple Zeytal CLI commands.

Debug

The --debug option, shorthand -d, can be used to provide a more verbose output when running Zeytal CLI commands.

terminal

$
pnpm zeytal --debug

Help

The --help option, shorthand -h, can be used to display more information about Zeytal CLI commands.

terminal

$
pnpm zeytal --help

terminal

$
pnpm zeytal assets --help

Current Working Directory

The --cwd option, shorthand -c, can be used to provide a working directory (that can be different from the current directory) when running Zeytal CLI commands.

terminal

$
pnpm zeytal --cwd=./path-to/current-working-dir

Zeytal CLI Commands

Learn how to use Zeytal CLI commands.

Command aliases

The zeytal command is an alias of the zeytal generate command.

Running one or the other will produce the same results.

zeytal assets

The zeytal assets command extracts and optimizes the SVGs you marked with an export setting from the Figma files you listed in your project’s dashboard.

You can use this command separately from the others if you want to generate assets only.

You can override the assets generation default settings in your CLI config file.

Usage

terminal

$
pnpm zeytal assets

Extended usage

terminal

$
pnpm zeytal assets --cwd=./path-to/root-dir

zeytal generate

The zeytal generate command generates your variables, styles, and assets.

Under the hood, it calls zeytal assets, zeytal styles, and zeytal variables exactly in that order.

The command is executable from the project’s current working directory or by specifying a current working directory path.

You omit generate in zeytal generate, as zeytal is the only command that operates without a subcommand. The following sections of the docs will use zeytal to refer to zeytal generate.

You can also use the shorthand gen depending on what you prefer.

You can override the variables, styles, and assets generation default settings in your CLI config file.

Usage

terminal

$
pnpm zeytal generate

terminal

$
pnpm zeytal gen

terminal

$
pnpm zeytal

Extended usage

terminal

$
pnpm zeytal --cwd=./path-to/root-dir

terminal

$
pnpm zeytal --debug

terminal

$
pnpm zeytal --help

zeytal styles

The zeytal styles command extracts and transforms the saved and implemented Figma styles from the Figma files you listed in your project’s dashboard.

We stress the word implemented here because Figma’s REST API is what it is; it’s simply impossible to fetch styles not implemented in your designs.


To ensure all your styles are retrieved and transformed by the CLI, save them AND use them in your files.

You can use this command separately from the others if you want to generate styles only.

You can override the styles generation default settings in your CLI config file.

Usage

terminal

$
pnpm zeytal styles

Extended usage

terminal

$
pnpm zeytal styles --cwd=./path-to/root-dir

terminal

$
pnpm zeytal styles --debug

terminal

$
pnpm zeytal styles --help

zeytal variables

The zeytal variables command transforms the Figma variables collections from the pre-extracted Figma files listed in your project’s dashboard.

Note: You must manually extract your variables with the Zeytal Figma Plugin. For a more detailed explanation, see the the dashboard variables tab guide.

You can use this command separately from the others if you want to generate variables only.

You can override the variables generation default settings in your CLI config file.

Usage

terminal

$
pnpm zeytal variables

Extended usage

terminal

$
pnpm zeytal variables --cwd=./path-to/root-dir

terminal

$
pnpm zeytal variables --debug

terminal

$
pnpm zeytal variables --help