Introduction

Generate, check, and hand off Tonex color systems from the terminal.

The CLI is the terminal surface for Tonex. It runs the same engine as the web app, but in a form that fits scripts, CI, and agents: input a seed, print a deterministic artifact, then verify the pairings that matter.

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

That command gives you a role-mapped color system from one seed. The output target can be shadcn CSS, Material JSON, a DESIGN.md color block, or the raw Tonex role set for an agent to map into another tool.

The CLI loop

Most CLI work follows the same loop:

Generate a color system from a seed.
Map the roles into the target surface, either through a native exporter or an agent/script.
Check the final foreground/background pairs against WCAG.
Adjust only when you need a precise token-level nudge, then check again.

generate is the common path. check is the safety gate. adjust is a surgical tool, not a replacement for the generator.

Built for agents

The CLI is designed to be read and driven by agents without guessing:

Standard output carries the artifact. Redirect it into files or let an agent read it directly.
tonex describe emits the contract as JSON. It lists commands, flags, targets, bindings, contrast policy, and exit codes.
Exit codes are stable. 0 means clean, 1 means a contrast gate failed, and 2 means the command or input was invalid.

That separation matters: a contrast failure means the colors need a remedy; a usage error means the call needs to be fixed.

Subcommands

Command	Use it to
`generate`	Derive a theme from a seed and print it.
`check`	Audit WCAG contrast for a theme or explicit pairs.
`adjust`	Shift named tokens by relative HCT tone/chroma deltas.
`describe`	Print the machine-readable CLI surface.

Run npx @tonex-dev/cli@latest --help for human-readable usage, or npx @tonex-dev/cli@latest describe for the machine-readable contract.