CLI

Install the global `systhema` CLI, the command summary, proxied project commands and canary builds.

On this page

@systhemaui/cli is the user-facing global CLI for the Systhema framework. It scaffolds new projects, upgrades existing ones, runs codemods, manages bundled agent skills, and proxies through to the project-local commands shipped by @systhemaui/core.

The single binary is systhema. After install:

systhema --help

InstallationLink to this section

Requires Node.js 22 or newer. The CLI's bundled process runner uses Set.prototype.union, which Node 20 does not have; on an older Node the CLI exits with a one-line message telling you the version it found. Scaffolded projects themselves still run on Node 20.9+.

One-shot (no install)Link to this section

pnpm dlx @systhemaui/cli@latest <command>

pnpm dlx downloads the CLI on demand and runs it. Useful for first-time scaffolding without committing to a global install.

Global install (recommended for ongoing work)Link to this section

pnpm add -g @systhemaui/cli

After install, systhema is on your $PATH everywhere. Update with systhema self-update.

CommandsLink to this section

systhema [options] [command]

  info                          Show CLI, environment, and project diagnostics
  self-update                   Update the globally-installed Systhema CLI
  create [name]                 Scaffold a new Systhema project
  setup [feature]               Add or reconfigure integrations on an existing Payload project
  upgrade [target]              Upgrade an existing Systhema project
  codemod [name]                Run a single code codemod (debugging / manual use)
  migrate [name]                Run a single data migration (post-upgrade hook) by id
  doctor                        Diagnose project health and auto-fix issues
  generate-references           Generate agent-facing TOON references
  generate-palette <inputs...>  Generate an 11-stop Tailwind-style palette from hex colors
  design <sub>                  Design-system generator — the Systhema Design platform in the terminal
  skills                        Manage bundled Systhema skills

  Proxied to project-local systhema-core (run inside a project):

  sync [args...]                Run copy-files + generate-types + references
  copy-files [args...]          Copy Systhema design tokens into the project
  generate-types [args...]      Generate Systhema TypeScript types
  refresh-cache                 Refresh the package token cache from generated artifacts
  init [args...]                Initialize a Systhema config in this project
  create-config [args...]       Create a Systhema config file
  generate-env-secrets [args...] Generate environment secrets
  migrate-tokens [args...]      Migrate old-format tokens to W3C DTCG
  obfuscate [dir]               Post-build obfuscation pass (default dir: .next)
  cookies <sub> [args...]       Cookie consent scanner / seeder / OCDB cache
  payload [args...]             PayloadCMS-specific helpers

The Design CLI documents systhema design commands.

-V / --version prints the CLI version. -h / --help works on every subcommand.

Two CLIsLink to this section

Each package that ships a CLI has its own bin:

Package	Bin	What it does
`@systhemaui/cli`	`systhema`	Global CLI: scaffolds, upgrades, runs codemods, manages skills, proxies project commands.
`@systhemaui/core`	`systhema-core`	Project-local helper: `sync`, `copy-files`, `generate-types`, `init`, `payload <sub>`, `migrate-tokens`.

Project package.json scripts use systhema-core directly so they don't depend on the global CLI being installed. The global CLI's upgrade command runs a codemod (rename-systhema-bin) when needed to keep old systhema X script invocations migrated to systhema-core X.

Project-local commandsLink to this section

The following commands require a Systhema project (a package.json with @systhemaui/core installed and a systhema.config.* somewhere). They're proxied through to the systhema-core binary shipped by @systhemaui/core.

systhema sync                  # = pnpm exec systhema-core sync (artifacts + references)
systhema init --payload        # = pnpm exec systhema-core init --payload
systhema payload create-config # = pnpm exec systhema-core payload create-config

Direct invocation also works:

pnpm exec systhema-core sync
pnpm systhema-core init

Project package.json scripts use the direct form so they don't depend on the global CLI. The 1.6.0 rename-systhema-bin codemod (run automatically by systhema upgrade) rewrites old systhema X script invocations to systhema-core X.

Each project-local command is documented on systhema-core. To test an unreleased build, see Canary and internal builds.