Migration guide with callouts and shortcut table

Default content

{
  "eyebrow": "Migration guide",
  "title": "Upgrading to v5",
  "lead": "CLI 5 brings config schema 5, a single token variable and new dashboard shortcuts. Most projects upgrade in under ten minutes; the steps below are in the order we recommend.",
  "versions": [
    {
      "label": "CLI",
      "value": "5.0.2"
    },
    {
      "label": "Config schema",
      "value": "5"
    },
    {
      "label": "Node.js",
      "value": "≥ 20"
    },
    {
      "label": "Released",
      "value": "Oct 8, 2026"
    }
  ],
  "deprecation": {
    "badge": "Deprecated",
    "title": "`RIVET_API_KEY` and `rivet env add`",
    "text": "Both still work in 5.x and print a warning on every run. Switch to the replacements before 6.0, when the old names are removed and CI deploys that use them fail with `E_AUTH_MISSING`.",
    "removal": "Removed in 6.0 · Jan 15, 2027",
    "labels": {
      "before": "v4",
      "after": "v5"
    },
    "replacements": [
      {
        "before": "RIVET_API_KEY",
        "after": "RIVET_TOKEN"
      },
      {
        "before": "rivet env add",
        "after": "rivet env set"
      },
      {
        "before": "build.publish",
        "after": "build.output"
      }
    ]
  },
  "labels": {
    "contents": "In this guide",
    "copy": "Copy",
    "copied": "Copied"
  },
  "sections": [
    {
      "title": "Update the CLI",
      "body": [
        {
          "type": "code",
          "language": "shell",
          "label": "Terminal",
          "code": "$ npm install -g @rivetlane/cli@5\n$ rivet --version\nrivet/5.0.2 darwin-arm64 node-v20.17.0"
        },
        {
          "type": "callout",
          "tone": "note",
          "text": "v4 and v5 share the same project link and login. To go back, run `npm install -g @rivetlane/cli@4`; nothing in your project changes until step 2."
        }
      ]
    },
    {
      "title": "Migrate rivetlane.toml",
      "body": [
        {
          "type": "paragraph",
          "text": "`rivet migrate config` rewrites the file to schema 5: it adds `schema = 5` and renames `build.publish` to `build.output`. Comments and ordering are kept."
        },
        {
          "type": "code",
          "language": "shell",
          "label": "Terminal",
          "code": "$ rivet migrate config --dry-run\n~ build.publish → build.output\n+ schema = 5\n$ rivet migrate config\n✓ Migrated rivetlane.toml to schema 5"
        },
        {
          "type": "callout",
          "tone": "tip",
          "title": "Check it in CI first",
          "text": "Add `rivet migrate config --dry-run --check` to your pipeline. It exits with code 1 while any project in the repo is still on schema 4."
        }
      ]
    },
    {
      "title": "Rename the token variable",
      "body": [
        {
          "type": "paragraph",
          "text": "Replace `RIVET_API_KEY` with `RIVET_TOKEN` in every CI provider and secret store. The value does not change."
        },
        {
          "type": "callout",
          "tone": "warning",
          "title": "Old pipelines keep passing — for now",
          "text": "5.x falls back to `RIVET_API_KEY` with a warning, so nothing breaks today. Search your CI logs for `W_DEPRECATED_TOKEN_VAR` to find the jobs you missed."
        }
      ]
    },
    {
      "title": "Review env pull before you run it",
      "body": [
        {
          "type": "paragraph",
          "text": "`rivet env pull` now writes exactly what the `development` scope contains, so local runs match deploys."
        },
        {
          "type": "callout",
          "tone": "danger",
          "title": "`.env.local` is overwritten",
          "text": "v4 merged pulled values into `.env.local`; v5 replaces the file. Local-only keys are lost unless you pass `--merge` or back the file up first."
        }
      ]
    }
  ],
  "shortcuts": {
    "title": "Dashboard shortcuts",
    "text": "The v5 dashboard adds two-key navigation. Press ? anywhere to see this list.",
    "labels": {
      "action": "Action",
      "keys": "Shortcut",
      "change": "In v5",
      "then": "then",
      "new": "New",
      "changed": "Changed",
      "unchanged": "Unchanged",
      "was": "was"
    },
    "rows": [
      {
        "action": "Open the command menu",
        "keys": [
          "⌘",
          "K"
        ],
        "sequence": false,
        "change": "unchanged"
      },
      {
        "action": "Go to deployments",
        "keys": [
          "G",
          "D"
        ],
        "sequence": true,
        "change": "new"
      },
      {
        "action": "Go to previews",
        "keys": [
          "G",
          "P"
        ],
        "sequence": true,
        "change": "new"
      },
      {
        "action": "Redeploy the current deployment",
        "keys": [
          "⇧",
          "R"
        ],
        "sequence": false,
        "change": "changed",
        "was": "R"
      },
      {
        "action": "Stream logs",
        "keys": [
          "L"
        ],
        "sequence": false,
        "change": "new"
      },
      {
        "action": "Show all shortcuts",
        "keys": [
          "?"
        ],
        "sequence": false,
        "change": "unchanged"
      }
    ]
  },
  "help": {
    "text": "Stuck on a step? Paste the output of `rivet doctor` into a support request.",
    "link": {
      "label": "Contact support",
      "href": "#"
    }
  }
}