---
title: "systhema-core"
description: "The project-local CLI: `init`, `sync`, `copy-files`, `generate-types`, `refresh-cache`, `clean`, `generate-env-secrets`, `create-config`, `migrate-tokens`, `obfuscate`, `payload`."
requested_language: fr
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/fr/next/cli/systhema-core
version: unreleased (main)
docs_index: https://docs.systhema.app/fr/next/llms.txt
---
> This page isn't translated yet. Showing English.


The `@systhemaui/core` package ships a project-local CLI binary called `systhema-core`. All commands are intended to run inside a consumer project (not the monorepo). Project `package.json` scripts use this binary directly:

```json
{
  "scripts": {
    "sync": "systhema-core sync"
  }
}
```

You can also invoke commands from the global [`@systhemaui/cli`](https://docs.systhema.app/fr/next/cli.md), which proxies them to `systhema-core`. For example, `systhema sync` proxies straight to `systhema-core sync` — which itself generates the agent-facing references as its final step.

## `init`

Initialize Systhema configuration files in the current project.

```bash
pnpm systhema-core init
```

Flags:

- `--ts` / `-typescript` — emit TypeScript versions of the config files.
- `--src` / `-source-dir` — place the Systhema config in `src/` instead of the project root.
- `--react` / `-react` — set `packages.react = true` in the generated config so React/Next safelists are produced.
- `--payload` / `-payload` — full PayloadCMS setup (auto-enables `--ts`, `--react`, `--postcss`).
- `--tw-legacy` / `-tw-legacy` — also create a legacy `tailwind.config.{js,ts}`.
- `--postcss` / `-postcss` — also create a `postcss.config.{js,mjs}`.
- `--override` / `--o` — overwrite existing files without prompting.

Examples:

```bash
# Plain JS Next.js project.
pnpm systhema-core init

# TypeScript + React.
pnpm systhema-core init --ts --react

# Full Payload setup.
pnpm systhema-core init --payload
```

This creates:

- `systhema.config.{ts,js}` — main Systhema configuration file.
- `tailwind.config.{ts,js}` — only when `--tw-legacy` or `--payload` is passed.
- `postcss.config.{js,mjs}` — only when `--postcss` or `--payload` is passed.

## `copy-files`

Copy the project's design-token manifest and token files into `<project>/.systhema/artifacts/tokens/`. These artifacts now live in your repo (not `node_modules`), so a `pnpm install` no longer wipes them.

```bash
pnpm systhema-core copy-files
```

The command:

1. Searches for `systhema.config.{ts,js,json}` in the project root and `src/`.
2. Reads the `manifest` property to locate token files.
3. Copies the manifest and referenced token files to `.systhema/artifacts/tokens`.
4. Generates a `tokenMap.{ts,js}` in `.systhema/artifacts/` with `with { type: 'json' }` on every JSON import.
5. Writes `.systhema/artifacts/.generator.json` with `{ version, format: 2 }` after token generation succeeds. Existing `types.*` and `safelist.txt` files are preserved; run `generate-types` or `sync` to refresh them. A generation failure removes the stamp and fails the command.

> [!NOTE]
> Systhema mirrors `.systhema/artifacts/` into the `@systhemaui/core` package's `tmp/` cache at build and SSR time (via `refreshTmpFromSystemaDir`), so the Tailwind plugin and the `@systhemaui/core/tmp/*` import paths keep resolving. Those import paths are unchanged.
>
> The mirror accepts artifacts stamped with the current artifact format, regardless of the generating package version. Committed artifacts remain usable across canary releases without a sync when their format is compatible. Unstamped artifacts and incompatible formats are skipped with a warning. Run `systhema-core sync` to replace them from the configured source tokens. This prevents an older generator from overwriting a freshly installed package during an upgrade.
>
> The mirror compares **contents**, never timestamps. A package install stamps `node_modules` with the install time, which is routinely newer than a checked-out (or `COPY`-ed) `.systhema/artifacts` tree — so a timestamp comparison would silently keep the package's shipped defaults on exactly the environments that matter (CI, a Docker build, a reinstall after an upgrade). It also writes temp-then-rename rather than in place, because pnpm hardlinks `node_modules` from its global content-addressable store and an in-place write would mutate the copy shared with every other project on the machine. Files the project no longer carries are pruned from the mirrored subdirectories, so a theme file removed from your manifest cannot linger as a phantom option.
>
> If the mirror cannot run at all — an unresolvable `@systhemaui/core`, or a read-only `node_modules` in a hardened image — it prints a one-time warning naming the consequence (token-derived option lists may be stale) instead of failing silently. `systhema doctor`'s `stale-token-artifacts` check reports the same condition from the outside, and `systhema doctor --fix` resolves it by running `sync`.

If no manifest is configured, falls back to the built-in defaults shipped in `@systhemaui/core/src/tokens/`.

## `generate-types`

Generate TypeScript types from the synced design tokens.

```bash
pnpm systhema-core generate-types
```

The command:

1. Reads token files from `.systhema/artifacts/tokens`.
2. Extracts variant information (color modes, breakpoints, layout backgrounds, etc.).
3. Writes `.systhema/artifacts/types.{ts,d.ts,js}`.
4. Writes a Tailwind safelist to `.systhema/artifacts/safelist.txt`.

The generated types include:

- `ColorSystem` — your color modes (e.g. `'default' | 'dark'`).
- `ResponsiveSizing` — your breakpoint names (e.g. `'sm' | 'md' | 'lg'`).
- `LayoutBackground` — background variants (e.g. `'main' | 'alternative'`).
- `GapSize` — gap variants (e.g. `'none' | 'xs' | 'sm' | 'md' | 'lg'`).
- `ButtonVariant` / `CardVariant` / `AccordionVariant` — variants from your tokens.
- `AspectRatio` — pre-defined aspect ratios.

## `sync`

Regenerate artifacts from the configured token source, run `generate-types`, stamp the successful output, and mirror it before loading token-dependent modules. Type generation failures leave the stamp absent and fail the command. Then run `generate-references` for token and type artifacts plus the agent-facing TOON references at `.systhema/references/tokens/`. This is the one to run after editing tokens, the config, or upgrading `@systhemaui/core`. `.systhema/.meta.json` stays byte-stable when the generated artifacts do not change. Its `generatedAt` records the last sync that changed the version, source manifest, or generated artifacts.

```bash
pnpm systhema-core sync
```

> [!NOTE]
> The global CLI's `systhema sync` runs the identical pipeline (it proxies to `systhema-core sync`). Reference generation is part of `systhema-core sync` itself, so a project's own `pnpm sync` keeps `.systhema/references/` current without the global CLI installed.

Reference generation rewrites every file under `.systhema/references/tokens/` on each run, so there is nothing to migrate when the values or the serialization move: upgrade, sync, done. The files are [TOON](https://toonformat.dev); the format, including the tabular blocks and the quoting of `#`-leading values, is documented under [`systhema generate-references`](https://docs.systhema.app/fr/next/cli/generate-references.md#the-reference-format).

### `systhema sync` vs `systhema-core sync`

- **`systhema-core sync`** runs `copy-files` + `generate-types` **and then `generate-references`** — the full pipeline (token/type artifacts **and** the agent-facing TOON references at `.systhema/references/tokens/`). Project-local; no global CLI required.
- **`systhema sync`** proxies straight to `systhema-core sync` (so it runs the identical pipeline) and adds the global CLI's post-command doctor nudge.

The two are equivalent for artifacts + references — `systhema sync` is just the friendlier global entry point. Because the project-local form already produces references, a scaffolded project's `pnpm sync` keeps `.systhema/references/` in step on its own, with or without the global CLI installed.

## `refresh-cache`

Refresh the installed package cache from existing generated artifacts without running the full sync pipeline.

```bash
pnpm systhema-core refresh-cache
```

Templates run this after install. It is a no-op when `.systhema/artifacts` is absent, then prints the `pnpm sync` command needed to generate artifacts before the first type check.

## `clean`

Remove the project's generated artifacts and reset the cached defaults.

```bash
pnpm systhema-core clean
```

Deletes `<project>/.systhema/` and clears the `@systhemaui/core` package's `dist/tmp/` cache back to its shipped defaults. The artifacts are regenerated on the next build or `systhema-core sync`. The command loads only filesystem utilities, so it also works when `dist/tmp/tokenMap.js` cannot be parsed or imported. `sync` can repair that cache directly without running `clean` first. Use `clean` when you want to remove all generated project state.

## `generate-env-secrets`

Generate cryptographically secure secrets for environment variables.

```bash
pnpm systhema-core generate-env-secrets
```

Common flags:

- `--input <path>` / `-i <path>` — input file (default: `.env`).
- `--include <names>` — comma-separated variable names to generate secrets for.
- `--exclude <names>` — comma-separated variable names to skip.
- `--length <n>` / `-l <n>` — secret length (default: `24`).
- Character set flags — `--only-numbers`, `--only-letters`, `--lowercase`, `--uppercase`, `--lowercase-and-numbers` (default), `--uppercase-and-numbers`, `--mixed`, `--mixed-and-symbols`, `--all`, etc.

Examples:

```bash
# Generate secrets for any *_SECRET variable found in .env.
pnpm systhema-core generate-env-secrets

# Specific variables only, custom length, uppercase letters + numbers.
pnpm systhema-core generate-env-secrets \
  --include=API_KEY,DATABASE_URL --length=32 --uppercase-and-numbers

# Read from a different file with all character types.
pnpm systhema-core generate-env-secrets --input=.env.local --all
```

## `create-config`

Create configuration files without running other initialization logic. Accepts the same flags as `init`.

## `migrate-tokens`

Convert old-format token files (the legacy community Figma plugin format) to the W3C DTCG format that current Systhema expects.

```bash
pnpm systhema-core migrate-tokens
```

Use this if you're upgrading a project whose `src/tokens/` was exported before the official `@systhemaui/figma` plugin was used as the source of truth.

[Migrating legacy tokens](https://docs.systhema.app/fr/next/design/legacy-tokens.md) covers the whole conversion.

## `cookies`

Cookie-consent helpers: `scan`, `seed` and `update-db`. See [systhema cookies](https://docs.systhema.app/fr/next/cli/cookies.md).

## `payload`

PayloadCMS-specific helpers. Only run inside PayloadCMS projects.

Subcommands:

- `create-config` — generate `src/payload.config.ts` already wrapped in `withSysthema()`.
- `create-app-files` — generate the Next.js App Router files Systhema's Payload plugin needs (`src/app/(site)/...`, sitemaps, the catch-all `[[...segments]]` route, etc.). Templates are classified as either **managed** (framework glue — always overwritten with `--override`) or **scaffold** (starter files the user owns — only written when missing, preserved across upgrades). Managed: `src/proxy.ts` and the routes under `src/app/(site)/(systhema)/`. Scaffold: `src/app/layout.tsx` (with `src/seo-defaults.ts`, written only together with a new layout), `src/app/robots.txt/route.ts`, `src/app/(site)/globals.css`, `src/app/(site)/not-found.tsx`, `src/app/(site)/template.tsx`, `public/systhema-icon.svg`, the `storage/.gitkeep` markers, and Payload's route group `src/app/(payload)/` (layout, `custom.scss`, the Admin page and 404, a starter `admin/importMap.js`, and the REST and GraphQL routes). The route group is written whole, and only when the project has no `src/app/(payload)/` directory; a project that has one, even partially, is left alone. After writing it the command asks you to run `payload generate:importmap`. Every one of these is the Payload starter template's own file, bundled into the package at build time, so `create-app-files` and `systhema create` scaffold the same bytes. With [locales](https://docs.systhema.app/fr/next/nextjs/locales.md) configured, `template.tsx` is replaced by the scaffold `src/app/(site)/shell.tsx` plus two managed boundary files under `src/app/(site)/(systhema)/[[...segments]]/`.

  Systhema records the bytes it writes for each managed file in `.systhema/managed-files.json` (commit it). That ledger is also how `create-app-files` reads a **deletion**: a managed file the ledger has a hash for, but that is no longer on disk, was removed on purpose, so the run reports `Skipped <path> (deleted locally).` and leaves it gone, keeping the ledger entry so the decision holds on every later upgrade. A managed path the ledger has never seen is still created, which covers a first run and any managed file a new release adds. Deleting `public/systhema-icon.svg` also drops the admin favicon, because `withSysthema()`'s `admin.meta.icons` points at it.

- `clean-defaults` — remove default PayloadCMS template files (`src/app/(frontend)`, `src/app/my-route`, `src/collections`).

Flags:

- `--override` / `-o` — overwrite existing files without prompting.
- `--yes` / `--force` — skip the confirmation for `clean-defaults`.

```bash
pnpm systhema-core payload create-config
pnpm systhema-core payload create-app-files --override
pnpm systhema-core payload clean-defaults --force
```

## `obfuscate`

`systhema-core obfuscate [dir]` (default dir: `.next`) is the post-build half of `optimization`, and runs two passes:

- **CSS variables** (`optimization.obfuscateVariables`) — repairs `var(--…)` references the generation-time rename couldn't reach (your own `globals.css`, CMS-authored inline styles) and warns loudly about any that stay orphaned. Safe on every project.
- **Class names** (`optimization.obfuscateClasses`) — the precise, tag-safe class rename. **Prerender-only**: it refuses to run (non-zero exit, reasons listed) on a build that renders pages at runtime — a PayloadCMS project, ISR routes, on-demand dynamic routes, or a `force-dynamic` / `revalidate` export. Pass `--allow-dynamic` to override on a genuinely fully-prerendered site.

`systhema obfuscate` forwards to it verbatim — the optional `[dir]` and `--allow-dynamic` are passed straight through — so either binary works from inside a project.

Templates don't ship a `build:obfuscated` script by default — to opt in, add one (e.g. `"build:obfuscated": "next build && cross-env NODE_ENV=production systhema-core obfuscate"`). The command is a no-op unless the config opts in **and** `NODE_ENV === 'production'`. See [Production CSS optimization](https://docs.systhema.app/fr/next/styling/optimization.md#class-obfuscation).