docs: add v3→v4 migration guide (sentry-cli → sentry) (#1201)

Adds a migration guide for the upcoming **major release** (v3 → v4),
where the legacy Rust `sentry-cli` is replaced by the new TypeScript
`sentry` CLI.

New page: `docs/src/content/docs/migrating-from-v3.md` (wired into the
**Getting Started** sidebar, between Installation and Self-Hosted).

## Covers
- **The rename** — `sentry-cli` → `sentry` binary, `@sentry/cli` →
`sentry` npm package, with install/uninstall steps for
npm/brew/curl/npx.
- **Command changes**, grouped for quick scanning:
- *Still work unchanged* (`info`, `send-event`, `send-envelope`,
`bash-hook`, `sourcemaps`, `debug-files`, `react-native …`).
- *Renamed groups* (plural → singular: `releases`→`release`,
`projects`→`project`, …) with a note that bare plurals still work as
list shortcuts.
- *Moved* (`login`→`auth login`, `update`→`cli upgrade`,
`uninstall`→`cli uninstall`, `deploys`→`release deploys`,
`upload-dif`/`upload-dsym`→`debug-files upload`,
`difutil`→`debug-files`, `upload-proguard`→`proguard upload`).
  - *Removed* (`send-metric`).
- **A copy-paste `sentry-cli()` shim** that transparently translates
every moved/renamed command to its v4 form, so existing scripts and
muscle memory keep working during migration (the user-requested
"practical alternatives").
- **Output & scripting** (`--json` instead of screen-scraping,
`NO_COLOR`/`SENTRY_PLAIN_OUTPUT`), **OAuth device-flow auth** (tokens
still honored), **semantic exit codes**, **debug-ID-first sourcemaps**,
and **config/`.sentryclirc` backward-compat**.

All command mappings were verified against the actual v4 route map
(`src/app.ts`), `src/commands/`, and the existing
exit-codes/configuration docs. `cd docs && pnpm run build` passes (page
renders, no broken links).

> Note: I inferred the release will be branded **v4**; if it lands under
a different version the title/headings are a trivial find-replace.

Author: BYK

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
     outputs:
       skill: ${{ steps.filter.outputs.skill == 'true' || startsWith(github.ref, 'refs/heads/release/') }}
       code: ${{ steps.filter.outputs.code == 'true' || startsWith(github.ref, 'refs/heads/release/') }}
+      codemod: ${{ steps.filter.outputs.codemod == 'true' || startsWith(github.ref, 'refs/heads/release/') }}
       build-targets: ${{ steps.targets.outputs.matrix }}
       nightly-version: ${{ steps.nightly.outputs.version }}
     steps:
@@ -80,6 +81,9 @@ jobs:
               - 'package.json'
               - 'pnpm-lock.yaml'
               - '.github/workflows/ci.yml'
+            codemod:
+              - 'codemods/**'
+              - '.github/workflows/ci.yml'
       - name: Compute build matrix
         id: targets
         run: |
@@ -114,6 +118,22 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Nightly version: ${VERSION}"
 
+  codemod-test:
+    name: Codemod tests
+    needs: [changes]
+    if: needs.changes.outputs.codemod == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION_22 }}
+      # jssg fixtures live under codemods/sentry-v3-to-v4/tests/<case>/. The
+      # codemod CLI is pinned for reproducible runs (bump deliberately).
+      - name: Run jssg codemod tests
+        working-directory: codemods/sentry-v3-to-v4
+        run: npx codemod@1.12.7 jssg test -l typescript ./scripts/codemod.ts
+
   check-generated:
     name: Validate generated files
     needs: [changes]
@@ -888,7 +908,7 @@ jobs:
   ci-status:
     name: CI Status
     if: always()
-    needs: [changes, check-generated, build-binary, build-npm, build-docs, test-e2e, generate-patches]
+    needs: [changes, check-generated, build-binary, build-npm, build-docs, test-e2e, generate-patches, codemod-test]
     runs-on: ubuntu-latest
     permissions: {}
     steps:
@@ -897,7 +917,7 @@ jobs:
           # Check for explicit failures or cancellations in all jobs
           # generate-patches is skipped on PRs — that's expected
           # publish-nightly is excluded: it's infrastructure (GHCR push), not code quality
-          results="${{ needs.check-generated.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }}"
+          results="${{ needs.check-generated.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.generate-patches.result }} ${{ needs.codemod-test.result }}"
           for result in $results; do
             if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
               echo "::error::CI failed"
@@ -915,4 +935,8 @@ jobs:
             echo "::error::CI failed - upstream job failed causing check-generated to be skipped"
             exit 1
           fi
+          if [[ "${{ needs.changes.outputs.codemod }}" == "true" && "${{ needs.codemod-test.result }}" == "skipped" ]]; then
+            echo "::error::CI failed - upstream job failed causing codemod-test to be skipped"
+            exit 1
+          fi
           echo "CI passed"

.github/workflows/publish-codemod.yml

@@ -0,0 +1,37 @@
+name: Publish codemod
+
+# Publishes codemods/sentry-v3-to-v4 to the Codemod Registry
+# (https://codemod.com/registry) as `@sentry/cli-v3-to-v4`.
+#
+# Prerequisites (one-time, done on codemod.com):
+#   1. Own/create the `@sentry` scope in the Codemod Registry.
+#   2. Register this repository as a trusted publisher (OIDC) for that scope,
+#      so no long-lived API key is needed here.
+#
+# Trigger by pushing a tag like `codemod-v0.1.0`, or run manually.
+
+on:
+  push:
+    tags:
+      - "codemod-v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # OIDC token for the Codemod Registry trusted publisher
+
+jobs:
+  publish:
+    name: Publish to Codemod Registry
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+      - name: Publish
+        working-directory: codemods/sentry-v3-to-v4
+        # Pin the CLI in this OIDC-privileged job (avoid running unreviewed
+        # `@latest` with a publish token). Bump deliberately alongside the CI
+        # `codemod-test` job.
+        run: npx codemod@1.12.7 publish

biome.jsonc

@@ -18,6 +18,13 @@
       "!docs",
       "!test/init-eval/templates",
       "!dist-build",
+      // The codemod package is a self-contained Codemod (jssg) project with
+      // its own tooling/tests (`codemods/sentry-v3-to-v4`); it uses the
+      // `codemod:ast-grep` runtime import and intentionally "bad" v3 fixtures,
+      // so it must not be linted/formatted by the repo's Biome config.
+      "!codemods",
+      // custom-ca.ts blows past Biome's type-analysis limit when pulled into
+      // the module graph (internal Biome bug); force-ignore even via a test.
       "!!src/lib/custom-ca.ts"
     ]
   },

codemods/README.md

@@ -0,0 +1,38 @@
+# Codemods
+
+Automated migration transforms for the Sentry CLI.
+
+## `sentry-v3-to-v4.cjs`
+
+Migrates the legacy `@sentry/cli` v3 Node wrapper (`new SentryCli().releases.*`)
+to the v4 `sentry` package library API (`createSentrySDK()`).
+
+```bash
+# Run against your source (any path/glob jscodeshift accepts)
+npx jscodeshift -t codemods/sentry-v3-to-v4.cjs src/
+
+# Or straight from GitHub, without cloning:
+npx jscodeshift \
+  -t https://raw.githubusercontent.com/getsentry/cli/main/codemods/sentry-v3-to-v4.cjs \
+  src/
+
+# For TypeScript sources, pick the matching parser:
+npx jscodeshift --parser=tsx -t codemods/sentry-v3-to-v4.cjs src/
+```
+
+It rewrites:
+
+- the `@sentry/cli` import / `require` → `sentry`,
+- `new SentryCli(configFile, options)` → `createSentrySDK(options)`
+  (drops the removed `configFile` arg, renames `authToken` → `token`),
+- the `releases.*` method chain → the v4 `release.*` / `sourcemap.*` methods,
+- `execute(args)` → `run(...args)`.
+
+Because several option **shapes** changed between v3 and v4 (most notably
+`uploadSourceMaps({ include })` → `sourcemap.upload({ directory })`), the codemod
+does the mechanical rewrites and inserts `// TODO(sentry-v4): …` comments where a
+call needs a manual review rather than guessing. **Review the diff** after
+running it.
+
+See [Migrating from v3](https://cli.sentry.dev/migrating-from-v3/) for the full
+guide.

codemods/sentry-v3-to-v4/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+target/
+*.tgz

codemods/sentry-v3-to-v4/README.md

@@ -0,0 +1,54 @@
+# `@sentry/cli-v3-to-v4`
+
+A [Codemod](https://codemod.com) that migrates programmatic **`@sentry/cli` v3**
+usage (the `SentryCli` class) to the **v4 `sentry` package** (`createSentrySDK`
+factory + typed command methods).
+
+It is referenced from the CLI's
+[migration guide](https://cli.sentry.dev/migrating-from-v3/).
+
+## Usage
+
+```bash
+npx codemod @sentry/cli-v3-to-v4
+```
+
+Run it from your project root; it rewrites `.js`/`.ts` files in place. Review the
+diff afterward — the codemod inserts `// TODO(sentry-v4): …` comments wherever an
+option shape changed and needs a manual decision (it flags rather than guesses).
+
+## What it does
+
+- Rewrites the module specifier `@sentry/cli` → `sentry`, **keeping your local
+  binding name** (so re-exports and pass-throughs stay valid).
+- `new SentryCli(configFile?, options?)` → `SentryCli(options?)` — drops `new`
+  (v4's default export is the `createSentrySDK` factory) and the removed
+  `configFile` positional, and renames the `authToken` option to `token`.
+- Maps the release/sourcemap methods:
+  `releases.new`→`release.create`, `releases.finalize`→`release.finalize`,
+  `releases.setCommits`→`release["set-commits"]`,
+  `releases.uploadSourceMaps`→`sourcemap.upload`,
+  `releases.newDeploy`→`release.deploy`,
+  `releases.proposeVersion`→`release["propose-version"]`, and
+  `execute([...])`→`run(...)`.
+- Only touches files that actually import `@sentry/cli`, and only rewrites
+  method calls on instances it can see created via `new SentryCli(...)`.
+
+## Development
+
+```bash
+# Run the test fixtures (tests/<case>/input.ts + expected.ts)
+pnpm test
+
+# Type-check the transform
+pnpm run check-types
+
+# Update expected fixtures after an intentional change
+pnpm dlx codemod@latest jssg test -l typescript ./scripts/codemod.ts -u
+```
+
+## Publishing
+
+Published to the [Codemod Registry](https://codemod.com/registry) under the
+`@sentry` scope. See [`.github/workflows/publish-codemod.yml`](../../.github/workflows/publish-codemod.yml)
+for the tag-triggered, trusted-publisher (OIDC) release.

codemods/sentry-v3-to-v4/codemod.yaml

@@ -0,0 +1,25 @@
+schema_version: "1.0"
+
+name: "@sentry/cli-v3-to-v4"
+version: "0.1.0"
+description: "Migrate @sentry/cli v3 SDK usage to the v4 sentry package"
+author: "Sentry"
+license: "MIT"
+
+
+targets:
+  # Keep this aligned with the files matched in workflow.yaml.
+  languages: ["typescript"]
+
+keywords: ["sentry", "sentry-cli", "migration", "v3", "v4"]
+
+registry:
+  access: "public"
+  visibility: "public"
+
+capabilities: []
+
+workflows:
+  - name: main
+    default: true
+    path: workflow.yaml

codemods/sentry-v3-to-v4/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "sentry-v3-to-v4",
+  "version": "0.1.0",
+  "description": "Migrate @sentry/cli v3 SDK usage to the v4 sentry package",
+  "packageManager": "pnpm@10.x",
+  "type": "module",
+  "scripts": {
+    "test": "pnpm dlx codemod@1.12.7 jssg test -l typescript ./scripts/codemod.ts",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@codemod.com/jssg-types": "latest",
+    "typescript": "latest"
+  }
+}