kumiko upgrade
kumiko-upgrade [--from <version>] [--dir <path>] [--json] [--verbose] [--apply [--dry-run]]kumiko-upgrade --resolve <id|version>[,<id|version>...] --reason "<text>" [--not-applicable] [--dir <path>]In an app, the command is the kumiko-upgrade binary. It ships with
@cosmicdrift/kumiko-cli (since 0.351) and with @cosmicdrift/kumiko-dev-server,
so a scaffolded app already has it. Run it as bunx kumiko-upgrade from the
app directory. Inside the framework repository the same code runs as
kumiko upgrade.
The command reads changes.json from the framework core and the bundled
features and lists what is new since your baseline. The baseline is the
version in .kumiko/upgrade-state.json. Without that file it is the installed
package version. --from overrides both and ignores the marker.
Codemods
Section titled “Codemods”--apply runs the codemod of every pending breaking change, oldest version
first, against --dir (default: the current directory). The codemod scripts
ship inside the published @cosmicdrift/kumiko-framework package under
src/scripts/codemod/, so --apply works from a plain bun install. You do
not need a framework checkout. The scripts run as bun subprocesses.
After a successful run the marker moves to the installed version. If a codemod fails after earlier ones already ran, the command writes a partial marker at the highest pending version below the failed one and exits with code 1. The next run resumes at the failed codemod. If the first codemod fails, nothing is written.
--apply --dry-run reports what would run and writes nothing.
Manual migrations
Section titled “Manual migrations”A breaking change without a codemod is a manual migration. --apply prints it
as no codemod, manual migration required and records it in the marker under
pendingManual. Every later run lists the open entries:
⚠ 1 manual migration(s) still open: 0.352.0:2abbcda3 · 0.352.0 · Apps must import Temporal from @cosmicdrift/kumiko-types/temporal … Migrate them by hand, then mark them done: kumiko-upgrade --resolve <id|version> --reason "<what you did>" [--not-applicable]The id is <version>:<first 8 hex characters of the SHA-256 of the title>.
Copy it from the output. After you have made the change, close the entry:
bunx kumiko-upgrade --resolve 0.352.0:2abbcda3 --reason "switched 4 imports to kumiko-types/temporal"bunx kumiko-upgrade --resolve 0.352.0:2abbcda3 --reason "app never imported temporal-polyfill" --not-applicableA version works as the reference when exactly one entry of that version is
open. --resolve moves the entries from pendingManual to resolvedManual,
together with the resolution (migrated or not-applicable), your reason and
a timestamp. It leaves version and codemods alone and cannot be combined
with --apply.
The upgrade-state guard fails while an entry is still open.
Marker format
Section titled “Marker format”{ "version": "0.352.0", "appliedAt": "2026-10-08T09:12:44.512Z", "codemods": [ { "version": "0.271.0", "codemod": "scripts/codemod/migrate-db-raw.ts", "title": "`TenantDb.raw` is removed …" } ], "resolvedManual": [ { "id": "0.352.0:2abbcda3", "version": "0.352.0", "title": "Apps must import Temporal from @cosmicdrift/kumiko-types/temporal …", "resolution": "migrated", "reason": "switched 4 imports to kumiko-types/temporal", "resolvedAt": "2026-10-08T09:20:03.118Z" } ]}An open entry sits in pendingManual with id, version and title.
pendingManual and resolvedManual only appear when they are not empty.
Commit the file. The guards compare it with the installed version.
| Flag | Meaning |
|---|---|
--from <version> | Baseline for the report. Default: the marker version, else the installed version |
--dir <path> | App directory to check or apply against (default: cwd) |
--json | Machine-readable output: currentVersion, installedVersion, pending, pendingManual |
--verbose | Include the full migration details of every pending entry |
--apply | Run the codemods of pending breaking changes and write the marker |
--dry-run | With --apply: report what would run, write nothing |
--resolve <refs> | Mark open manual migrations as done. A ref is a full id or a version with exactly one open entry; separate several with commas |
--reason <text> | Required with --resolve, at most 500 characters |
--not-applicable | With --resolve: record the entries as not applicable instead of migrated |
--help, -h | Print the usage and exit |
Examples
Section titled “Examples”bunx kumiko-upgradebunx kumiko-upgrade --from 0.340.0 --verbosebunx kumiko-upgrade --jsonbunx kumiko-upgrade --apply --dry-runbunx kumiko-upgrade --applybunx kumiko-upgrade --resolve 0.352.0:2abbcda3 --reason "migrated Temporal imports"See also
Section titled “See also”- Upgrade Kumiko guide
kumiko changes, author changelog entries