Docs /Variflow Tokens

Command line

Every command runs through EE's command line, from the site root:

php system/ee/eecli.php <command> [options]

On a local stack, run it where the site's PHP runs: ddev exec php system/ee/eecli.php … (DDEV), lando php system/ee/eecli.php … (Lando), or inside the PHP container. php system/ee/eecli.php <command> --help lists a command's options.

Commands that work on one site take --site=<short name|id> (default: the first site). build, verify, usage:rebuild and rewrite:run also take --site=all.

variflow:init

Writes a starter token file and prints the config.php lines for it.

Option Does
--demo Write the Fernhaven Outfitters demo set (five schemes, derived colours, contrast pairs) instead of the starter
--path=<file> Where to write it (default: variflow_tokens_file, or system/user/config/tokens/site.tokens.json)
--force Overwrite an existing file

Exit codes: 0 written, 1 the file exists or can't be written.

variflow:verify

Checks the token file and compares it with the live build. Writes nothing.

Option Does
--file=<path> Check this file instead, for example a draft from variflow:import:tokens, against the site's content. The token file isn't changed
--json Print the result as JSON
-v List each framework map rule that was skipped

Exit codes: 0 no errors, 1 errors, 2 a config or file problem.

variflow:build

Checks, compiles and publishes. A build with errors publishes nothing and leaves the live build in place.

Option Does
--force Publish even when the output matches the live build
--json Print the result as JSON
-v List each framework map rule that was skipped

Exit codes: 0 published or unchanged, 1 errors, 2 a config, file or lock problem.

variflow:rollback

Republishes an earlier build's files, without recompiling.

Option Does
--to=<build id|previous> The build to put back; previous is the newest earlier build that still has its files
--list Show the build history instead (--json for JSON)

Exit codes: 0 rolled back (or listed), 2 refused.

variflow:usage:rebuild

Rebuilds the usage index from stored field data (channel fields, Grid, Fluid and Bloqs atoms), reports the count per source, and lists references the live build no longer has.

Option Does
--dry-run Count without writing

Exit codes: 0 done, 2 a problem.

variflow:rewrite:run

Settles pending renames and deprecations, and runs every queued rename rewrite the live build allows. It lists what's still waiting, and why.

Option Does
--dry-run Say what would run, without changing anything

Exit codes: 0 done, 2 a problem.

variflow:import

Writes a draft token file from a stylesheet's custom properties. It never writes your live token file.

php system/ee/eecli.php variflow:import themes/user/site/css/main.css
Option Does
--out=<path> Where to write the draft (default: next to the token file, as <name>.import.json)
--force Overwrite an existing draft
--json Print the draft instead of writing it

After the 14-day trial without a licence (Licensing), it prints the review only.

Exit codes: 0 written, 1 unreadable or empty CSS, 2 a config problem or a draft that already exists.

variflow:import:tokens

Writes a draft token file from a Figma, Tokens Studio or DTCG resolver export. Each mode becomes a scheme, holding only what differs from the default mode. It never replaces your live token file. See From Figma, Tokens Studio or Sketch.

php system/ee/eecli.php variflow:import:tokens figma-export --default=Light
php system/ee/eecli.php variflow:import:tokens tokens.json --schemes-from=Mode --default=Light --use=Density:Compact
php system/ee/eecli.php variflow:import:tokens Day.tokens.json Night.tokens.json --mode=Day.tokens.json:Light --mode=Night.tokens.json:Dark --default=Light

Give it the exported files, a folder (read recursively), or both.

Option Does
--default=<mode> The mode that becomes the base and the default scheme. Needed unless a resolver document names a default
--schemes-from=<group> The mode group whose modes become schemes: a Tokens Studio theme group, a Figma collection (its folder), a resolver modifier. Needed when there's more than one
--use=<group>:<mode> The mode another group uses (default: its first). Repeatable
--mode=<file>:<mode> A DTCG file's mode, or <file>:<group>/<mode> to put it in a group too. Default: Figma's com.figma.modeName, else the file name. Repeatable
--extras=<file> A Variflow extras file: layout presets, component variants, scheme labels and descriptions, group descriptions, flags such as hidden, and contrast pairs, merged in before the review. Its contrast pairs replace inferred ones
--no-labels Don't write inferred editor labels
--no-tiers Don't write inferred tiers
--no-pairs Don't write inferred contrast pairs
--no-derive Don't turn hover and pressed shades into derive rules
--out=<path> Where to write the draft (default: next to the token file, as <name>.import.json)
--use-as-token-file On a site with no token file: once the draft is written, rename it to the token file. On its own (no export named), use the draft already saved (--out, or the default). Refused, with nothing written, when the site has a token file. Needs a licence
--force Overwrite an existing draft
--json Print the review and the draft as JSON instead of writing. The review's inference has every proposal with its reason, and what wasn't inferred

Names of groups and modes match without regard to case. The review ends with what was inferred (see What's inferred): counts per kind, the derive rules, the pairs that fail, and the edge cases left as they are. With --extras, it then lists what the extras file added (+) and what it left out (!, with why), and the extras file's contrast pairs with any that fail; --json has them as extras. An extras file that isn't one exits 1, with the reason. When it can't decide (several mode groups, or no default), it lists the choices and writes nothing. After the 14-day trial without a licence it prints the review only.

Exit codes: 0 written, 1 unreadable or empty export, 2 a choice to make, a config problem or a draft that already exists.

variflow:convert

Converts a Text Input, Select, Radio or Color Picker field (or a Grid column, <grid field>:<column name>) to a Tokens field, mapping each stored value onto a token.

php system/ee/eecli.php variflow:convert hero_bg --dry-run
php system/ee/eecli.php variflow:convert hero_bg --accept-medium
php system/ee/eecli.php variflow:convert cards:swatch --settings=settings.json --map=map.json
Option Does
--settings=<json file> The Tokens settings, as a field stores them: {"variflow_mode": "token", "variflow_types": ["color"], "variflow_groups": ["color.surface"], "variflow_default": "color.surface.default"}. Default: the same suggestion as the control panel
--map=<json file> Decide values yourself: {"#FBFAF7": "color.surface.default", "#ff0000": "", "var(--x)": "keep"}, giving a token name, "" for the field default, or "keep" (with --keep-raw)
--accept-medium Map medium-confidence values to their nearest token. Without it, the command stops and lists them
--keep-raw Outliers keep their raw values instead of becoming the field default
--dry-run Show what would change; write nothing
--json Print the review and result as JSON
--resume=<id> Finish an interrupted conversion
--list Past conversions

Exact and High matches map on their own. After the 14-day trial without a licence, the command stops after the dry run.

Exit codes: 0 done or dry run; 1 refused (not convertible, unchecked medium values, values changed since the review, an unfinished conversion, unlicensed); 2 a config problem or a failed run.

variflow:convert:undo

php system/ee/eecli.php variflow:convert:undo <id> [--dry-run]

Puts the field's old type, settings and values back. Values an editor has changed since the conversion are left alone. It's refused if the field's type has changed again since. It never needs a licence.

Exit codes: 0 undone or dry run, 1 refused, 2 a problem.

variflow:doctor

Checks the set-up and says what to fix:

  • PHP and its extensions;
  • the EE version, the add-on's version and its database;
  • the token file;
  • the output folder, and the live CSS over HTTP;
  • the live build and its files;
  • the picker assets, the licence and queued work.
Option Does
--bench[=N] Also time a build of a generated N-token file (default 300): load, validate, compile and write, median of 3. It publishes nothing
--no-http Don't request the live CSS over HTTP
--json Print the results as JSON

Exit codes: 0 everything ok (warnings allowed), 1 a check failed.

Related