systhema-core

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:

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

You can also invoke commands from the global @systhemaui/cli, 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.

initLink to this section

Initialize Systhema configuration files in the current project.

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:

# 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-filesLink to this section

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.

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.

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

generate-typesLink to this section

Generate TypeScript types from the synced design tokens.

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.

syncLink to this section

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.

pnpm systhema-core sync

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 (opens in new tab); the format, including the tabular blocks and the quoting of #-leading values, is documented under systhema generate-references.

systhema sync vs systhema-core syncLink to this section

• 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-cacheLink to this section

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

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.

cleanLink to this section

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

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-secretsLink to this section

Generate cryptographically secure secrets for environment variables.

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:

# 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-configLink to this section

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

migrate-tokensLink to this section

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

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 covers the whole conversion.

cookiesLink to this section

Cookie-consent helpers: scan, seed and update-db. See systhema cookies.

payloadLink to this section

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

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

obfuscateLink to this section

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.