---
title: "Upgrading"
description: "Keep a project current with `systhema upgrade`: plans, codemods, token migrations, database hooks and canary builds."
requested_language: hu
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/hu/next/getting-started/upgrading
version: unreleased (main)
docs_index: https://docs.systhema.app/hu/next/llms.txt
---
> This page isn't translated yet. Showing English.


`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](https://docs.systhema.app/hu/next/cli/upgrade.md) is the full flag reference.

## Run an upgrade

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

```bash
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 applying

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

```bash
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](https://docs.systhema.app/hu/next/cli/upgrade.md#review-and-apply-a-saved-plan).

## Database steps

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`](https://docs.systhema.app/hu/next/cli/migrate.md). Run them before you start or deploy the upgraded app. [Database migrations](https://docs.systhema.app/hu/next/payload/database/migrations.md) explains the two kinds of database change and the safe order.

## Ongoing maintenance

- 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`](https://docs.systhema.app/hu/next/cli/setup.md).

## Canary and internal builds

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:

```bash
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](https://docs.systhema.app/hu/next/guides/recipes/upgrading-a-client-site.md).