Upgrading

systhema upgrade moves a project to a new Systhema release. It plans every change first, applies code and token migrations, bumps dependencies, and runs database steps only when you allow them. This page is the task flow; systhema upgrade is the full flag reference.

Run an upgradeLink to this section

Update the global CLI first, because systhema upgrade targets the CLI's own version by default:

systhema self-update
systhema upgrade

The command prints a plan and asks before it changes anything. It then:

1. Runs registered codemods on your source files (config-shape changes, prop renames, script updates).
2. Applies token migrations to src/tokens/*.json (additions, renames, modifications, removals and new collections).
3. Bumps @systhemaui/* and the peer dependencies in package.json. On a Payload project it aligns every installed @payloadcms/* package with payload.
4. Re-keys or test-applies your pnpm patches, and stops before writing anything if one cannot move safely.
5. Installs dependencies, refreshes Systhema's managed files, runs sync and, on Payload projects, regenerates the Payload types and import map.
6. Refreshes the agent skills the project already has installed.
7. With --allow-database, runs the post-upgrade database steps.

Migrations are idempotent. Running systhema upgrade again on the same version finishes an interrupted upgrade and otherwise reports that there is nothing to do.

Useful flags:

• --dry-run: print the plan and change nothing.
• --yes: skip prompts. It never opts into database steps.
• --no-install, --skip-tokens, --skip-peers, --skip <id>: leave out a phase or one migration.
• --no-git-check: allow a dirty working tree, for CI.

Review a plan before applyingLink to this section

For an unattended or reviewed upgrade, save the plan as JSON, get it approved, then apply exactly that plan:

systhema upgrade --dry-run --json > /tmp/systhema-upgrade-plan.json
systhema upgrade --apply-plan /tmp/systhema-upgrade-plan.json --yes

Choose --skip, --skip-tokens, --no-install, --no-skills, the patch flags and --allow-database when you generate the plan, after reviewing any database writes that flag includes. Applying refuses changed project files, a different CLI version or edited plan contents. See Review and apply a saved plan.

Database stepsLink to this section

Some releases change what is stored in a Payload project's database. Those steps write to whatever database DATABASE_URI selects, so they run only with --allow-database, or later and one at a time with systhema migrate. Run them before you start or deploy the upgraded app. Database migrations explains the two kinds of database change and the safe order.

Ongoing maintenanceLink to this section

• Re-run pnpm systhema-core sync after any design-token or config change.
• Keep your GITHUB_TOKEN active. Package installs fail immediately if it expires.
• Check in regenerated token files (src/tokens/) so every environment has the same baseline.
• Run systhema upgrade when new versions ship; it's idempotent and prints a plan before touching anything.
• Run systhema doctor any time to health-check the project (pending migrations, peer-dep drift, legacy/missing tokens, config sanity), or systhema doctor --fix to resolve the fixable findings in one git-safe step.
• On a Payload project, run systhema setup <database|email|maps|captcha|forms|redirects|ai|cloudflare|locales> to add, reconfigure, or turn off a feature you skipped or want to change, see systhema setup.

Canary and internal buildsLink to this section

When an internal snapshot is published, the internal dist-tag lets you test that build. Publishing is a separate release operation; a feature-branch push alone does not guarantee an available snapshot. Use it to test in-flight migrations and codemods on a real project:

systhema self-update --target internal
# or pin a specific build:
systhema self-update --target 1.5.0-internal.03f0516

Use an isolated checkout and a disposable database copy. Verify the diff and behavior there. Restoring tracked files alone does not revert dependency installs, generated files or database writes. See Upgrading a client site.