---
title: "Design CLI"
description: "`systhema design`: sessions, editing, export, import and apply from the terminal or an agent."
requested_language: cs
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/cs/design/systhema-design/cli
version: unreleased (main)
docs_index: https://docs.systhema.app/cs/llms.txt
---
> This page isn't translated yet. Showing English.


The [Systhema Design](https://docs.systhema.app/cs/design/systhema-design.md) 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 start

```bash
# 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.

## Sessions

A design session lives in `.systhema/design/`:

```text
.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 edit

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

| Group                               | What it covers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `design color` / `palette` / `mode` | The three-tier color model. `color set/get/list` edits primitives (`theme.600`), foundations (`foundations.bg`), and component tokens (`button.primary.normal.background`) — raw values or live **references** (`@primitives.theme.600`, `@foundations.text`) that cascade like in the app. `palette add/seed` generates 11-stop ramps from a seed (seeding `theme` re-points the brand-linked foundations, exactly like the app); `mode add/…` manages colorSystem modes with the same shipped-keys-hide semantics. `color check` runs an APCA contrast audit. |
| `design type` / `font`              | `type scale` sets base size, ratio (named scales like `majorThird` or a number), line-height curve, and tracking per breakpoint; `type show` prints the computed heading ladder. `type style h1 --size 64` fixes an individual property (the app's "detach"); `--link` re-attaches it. `font search/set` picks from the Fontsource catalog — the heading role keeps Systhema's bold intent (700, or the closest bold weight the family ships) while body stays Regular, both overridable with `--weight`; `font upload` converts your own TTF/OTF to woff2.     |
| `design layout`                     | The spatial knobs: grid gap, container margin, section padding, article & feature controls — per breakpoint (`--bp sm \| md \| lg \| all`).                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `design logo` / `favicon` / `seo`   | Logos (SVGO-optimized, scripts always stripped), the RealFaviconGenerator-style icon set (`favicon generate` writes favicon.ico, PNGs, maskable Android icons, an optional dark-scheme variant, site.webmanifest, and the `<head>` snippet), and SEO/OG metadata with linting (`seo check`) and code output (`seo code --format html \| next`).                                                                                                                                                                                                                 |
| `design token`                      | The escape hatch: `token set/get/unset/list` on raw diff paths (`responsiveSizing.lg.grid.default.gap`, `textStyles.H1.textTransform`, …) for anything the ergonomic commands don't cover.                                                                                                                                                                                                                                                                                                                                                                      |

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

### Renaming a color mode on a Payload project

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](https://docs.systhema.app/cs/payload/database/migrations.md#renaming-a-stored-design-key). Adding, duplicating and reordering modes are unaffected.

## Export, import, apply

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:

| Command                 | Output                                                                                                                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `design export config`  | `systhema.config.ts` with the `customTokens` object (references stay DTCG aliases; `--color-format hex \| rgba \| oklch`).                                                                 |
| `design export figma`   | The DTCG token `.zip` for the [Systhema Figma plugin](https://docs.systhema.app/cs/design/figma.md) — design in the terminal, hand off to Figma, import edits back.                                                   |
| `design export project` | A full overlay `.zip` for a fresh scaffold (`--target next \| payload`): tokens, config, fonts + `@font-face` CSS, favicon set, logos, SEO module, and an embedded `systhema.design.json`. |
| `design export agent`   | `systhema.design.json` (+ `--md` markdown diff) for AI-agent handoff.                                                                                                                      |
| `design export all`     | All of the above with canonical filenames (`--out-dir`, `--target`).                                                                                                                       |

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 agents

- `--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.

## Requirements

- **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.