Commands

Tonex is a subcommand CLI:

npx @tonex-dev/cli <command> [options]

The commands are generate, check, adjust, and describe. Flags use the --flag value form, or --flag=value, rather than key=value. Unknown flags are usage errors. Run tonex --help for the same reference in your terminal, or tonex describe for it as JSON.

Generate

Derive a theme from a seed and print it.

npx @tonex-dev/cli generate --seed "#6A9CFF" [options] > globals.css

Seed

Palette strategy

Output

shadcn binding

Surface shaping

Authored layers

These opt-in emissions cover the parts of a theme the engine doesn't derive on its own. See The authored layer.

npx @tonex-dev/cli generate --seed "#6A9CFF" > globals.css
npx @tonex-dev/cli generate --seed "#6A9CFF" --variant expressive --desaturate 0.5
npx @tonex-dev/cli generate --seed "#6A9CFF" --with-brand --chart-palette polychrome
npx @tonex-dev/cli generate --seed "#6A9CFF" --to colors
npx @tonex-dev/cli generate --seed "#6A9CFF" --to yaml --mode dark
npx @tonex-dev/cli generate --seed "#6A9CFF" --to json --format hex

Delivered projections carry their own recipe so a later agent can reproduce them. shadcn and yaml emit a leading command comment; json embeds the command in its description. colors emits structured recipe metadata because it is usually a transient read target. For the full --to colors → map by intent → check --pairs workflow, see Mapping to Other Tools.

Check

Audit WCAG contrast. Exit 0 clears the level; exit 1 means a text pair fails. Add --json to any form for machine-readable output, --aaa to raise the bar from AA to AAA, and --large on ad-hoc pair checks to use large-text thresholds.

npx @tonex-dev/cli check --seed "#6A9CFF" [--variant <name>] [--contrast <0..1>] [--mode light|dark] [--aaa] [--json]
npx @tonex-dev/cli check --seed "#6A9CFF" --find-contrast [--variant <name>] [--mode light|dark] [--aaa] [--json]
npx @tonex-dev/cli check "#1a1a1a" "#ffffff" [--aaa] [--large] [--json]
npx @tonex-dev/cli check --pairs '[["#1a1a1a","#ffffff"],["#888","#fff"]]' [--aaa] [--large] [--json]
npx @tonex-dev/cli check --seed "#6A9CFF" --pairs '[["--color-on-surface","--color-surface"]]' [--variant <name>] [--mode light|dark] [--aaa] [--json]

Example verdicts:

PASS — AA contrast — 134 pairs clear
FAIL — 3.68:1 below AA text (4.5)
FOUND — AAA clears at --contrast 0.9
re-derive: generate --seed #6A9CFF --variant cmf --contrast 0.9

--find-contrast exits 1 if even --contrast 1 cannot reach the level. The token-name form exits 2 on an unknown token name, with a did-you-mean.

Token names

Different surfaces use different names for the same role:

Use the --color- prefix for token-name checks and adjustments.

Adjust

Shift named tokens by a relative HCT delta and print before/after facts plus the gamut-clamped achieved delta. Exit 0 on a clean shift, 2 on a bad token name or malformed --shifts. It never gates contrast — run check for that.

npx @tonex-dev/cli adjust --seed "#6A9CFF" \
  --shifts '[{"mode":"light","token":"--color-surface","dTone":-4,"dChroma":2}]' [--json]

A shift result reports the requested and achieved movement:

light --color-surface  oklch(…) → oklch(…)   req t-4 c+2   got t-3.9 c+2.16

--shifts takes a JSON array of {mode, token, dTone?, dChroma?} entries, each with at least one axis. adjust also accepts the shared seed knobs (--variant, --contrast, --tint/--desaturate); the per-shift mode lives inside each entry, so there is no --mode flag.

Describe

Print the machine-readable surface — every command and flag from the same specs the parser validates against, the contrast verdict policy and thresholds, and the exit-code taxonomy.

npx @tonex-dev/cli describe

Top-level JSON keys include tool, exitCodes, commands, contrast, variants, targets, and bindings.

Exit codes