---
title: "Upgrade MainSDK"
description: "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."
section: "guides"
status: "Building for 0.5"
spec: "upgrade"
canonical: "https://mainsdk.dev/docs/guides/upgrade-mainsdk"
updated: "2026-10-28"
---

# 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.

Status: Building for 0.5 · Canonical: https://mainsdk.dev/docs/guides/upgrade-mainsdk · 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](https://mainsdk.dev/docs/interfaces/upgrade).