Upgrade MainSDK

Plan an upgrade, let one command move every MainSDK package and apply the release's codemods, read the pull request it opens, and find out when a security release is out.

Building for 0.5

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

You will move an app to a new MainSDK release and review the pull request. It takes about 10 minutes.

You need

A MainSDK app in a git repository with a clean working tree and a lockfile.
gh signed in, if you want the command to open the pull request.

1. See the plan

bash

npx mainsdk upgrade --to latest --plan

The plan lists the versions between yours and the target, each codemod, each manual step, each main.yaml move that applies to your file, and each call site of a call the target removes. It writes nothing.

2. Apply it

bash

npx mainsdk upgrade --to latest

The command creates chore/upgrade-mainsdk-<version>, moves every mainsdk and @mainsdk/* dependency to the one version, installs, and hands over to the newly installed CLI, which applies the notes in version order, runs sync, check and your test script, commits once and opens the pull request.

3. Read the pull request

The body holds the plan. A failure in sync, check or your tests gives MAIN-UPGRADE-0006: the branch is kept and the pull request is a draft that lists each failure. Steps marked manual are listed with file and line (MAIN-UPGRADE-0003) for you to do on the branch.

4. Watch for security releases

bash

npx mainsdk upgrade --check

It exits 1 with MAIN-UPGRADE-0005 when a release marked security is newer than yours. Run it in CI; the answer is cached for 24 hours, and mainsdk check shows it too.

5. Check that a contract did not break

When you vendor a provider's contract, or maintain your own, compare it with its pin before you move on:

bash

npx mainsdk contract diff --json

It exits 1 on a breaking change that is not released as a new major, such as a removed field or error code.

Check it worked

npx mainsdk check reports no MAIN-UPGRADE-0002 (every MainSDK package is at one version), and git log shows one commit on the upgrade branch. See Upgrades.

Was this page helpful?