Design CLI

The Systhema Design platform in the terminal. Everything the web-based generator does — colors, typography, layout, fonts, logos, favicon, SEO, four export targets, full round-trip import — as a systhema command group, plus one thing the browser can't do: applying the design directly into your project.

It exists for two audiences at once: humans who live in the terminal, and AI agents, for whom every command is non-interactive, deterministic, and --json-outputting. A design made in the web app continues seamlessly in the CLI and vice versa — both speak the same systhema.design.json artifact.

Quick startLink to this section

# A complete, tasteful starting design from a brand color and a font pairing:
systhema design new --seed '#0E4DA4' --heading-font 'Space Grotesk' --body-font Inter --yes

# See what it did:
systhema design status
systhema design diff

# Refine:
systhema design color set foundations.bg '#FAF7F2'
systhema design type scale --base 18 --ratio majorThird

# Ship it into the current Systhema project:
systhema design apply

Interactive versions exist too — systhema design new with no flags walks you through seed, fonts, and scale as a questionnaire.

SessionsLink to this section

A design session lives in .systhema/design/:

.systhema/design/
  design.json     # the design — the same systhema.design.json the web app exports
  assets/         # logos, favicon sources, OG image, uploaded .woff2 fonts
  cache/          # the Fontsource catalog cache (24h)
  dist/           # everything the export commands write

• The session directory is resolved from the nearest Systhema project root, or the current directory outside a project — so you can design before the project exists and apply after scaffolding. --session <dir> overrides.
• design.json stores a diff over Systhema's defaults — only what you changed. It is a valid web-app artifact: the Import dialog at Systhema Design accepts it directly, and design import accepts everything the web app exports.
• Every mutating command creates the session on first use, so you rarely need design init — reach for it to create an empty session up front, or to seed one from an existing design: design init --from <any export> (it refuses when a session already exists; use design import for that).
• design reset reverts a slice (or everything) to defaults.

What you can editLink to this section

The command groups mirror the web app's sidebar sections:

Every command documents itself: systhema design <cmd> --help includes examples.

Renaming a color mode on a Payload projectLink to this section

A colorSystem mode key is not only a token key on a Payload project — it is a stored value. Pages, posts, archives and every themed Lexical block keep the key you chose in the database, so renaming a mode leaves that content pointing at a mode that no longer exists (and on Postgres the next schema push fails outright, because those fields are enum columns).

mode rename therefore asks for confirmation inside a Payload project and prints a reminder afterwards; --yes accepts it non-interactively, which is also what --json mode requires. Migrate the stored values before you apply the rename — see Database migrations → Renaming a stored design key. Adding, duplicating and reordering modes are unaffected.

Export, import, applyLink to this section

The four export targets produce the same formats the web app does, plus an all shortcut that writes every one of them in a single run:

The config and Figma exports carry the colour overlay (palette anchors, mode polarities and manual foundation relations) as the web app does, so a design that goes out through the CLI and comes back keeps those editing choices.

design import <file> auto-detects every format (and pasted stdin via -), shows a recovery summary, and applies by replace or --mode merge. A merge combines the incoming overlay with the session's the same way the web app's import does. The previous session is kept as design.json.bak.

design apply writes the design into a Systhema project in place — src/tokens/*.json, the customTokens in systhema.config.ts (merged into an existing config), fonts, favicon files, logos, and the SEO metadata module — then runs the project's sync so generated artifacts refresh. It requires a clean git tree (--force to override), so a bad apply is one git checkout . away from undone. --dry-run lists every write.

For agentsLink to this section

• --json on any command prints exactly one JSON object: { ok, changes?, warnings?, error?, hint?, data? } (only ok is always present) — on failure, hint carries the recovery step or, when a near match exists, the did-you-mean suggestion.
• --yes skips every confirmation; nothing ever blocks on a prompt in --json mode.
• Unknown paths fail with a did-you-mean suggestion.
• The systhema:design skill (systhema skills install --name systhema:design --scope user) teaches the full workflow — including generating a design system from a client's brand book in a blank folder.

RequirementsLink to this section

• sharp (installed with the CLI) is needed only by favicon generate, export project, and apply when a favicon is configured — everything else works without it, and those commands fail with a clear install hint if its platform binary is missing.
• font search/font set fetch the Fontsource catalog (network, cached 24h); font upload and everything else work offline.