Distillation

🔴 (05:22) Package-manager upgrades through Homebrew/npm/pnpm/Bun/Yarn always require network access to fetch and install packages; --offline is supported only for curl-installed binaries, otherwise validateMethod() throws UpgradeError("unsupported_operation", "Offline upgrade is only supported for curl-installed binaries.").
🔴 (05:22) resolveTargetWithFallback() in packages/cli/src/commands/cli/upgrade.ts uses explicit offline mode only for curl installs. When switching channels without an explicit version, offline mode is rejected because the cached version belongs to the previous channel; the error instructs the user to rerun sentry cli upgrade with network access.
🔴 (05:22) resolveTargetWithFallback() reads the cached target before calling persistChannelFn(), because setReleaseChannel() clears the version-check cache when the channel changes. Explicit offline resolution returns offline: "explicit"; automatic network-error fallback returns offline: "network-fallback".
🔴 (05:22) Automatic cached-target fallback is allowed only when the installation method is "curl" and the caught error is UpgradeError with reason "network_error". Version lookup or validation failures such as version_not_found do not trigger fallback, and failure to find a cached target rethrows the original network error.
🔴 (05:22) resolveTargetVersion() always fetches the latest version before selecting versionArg or latest as the target. It returns "checked" for --check, returns "up-to-date" when CLI_VERSION === target unless forced or changing channels, and validates an explicitly pinned version with versionExists().
🔴 (05:22) Nightly builds are GitHub-only, so pinned nightly versions always use curl/GitHub lookup via versionExists("curl", target), regardless of the current installation method.
🔴 (05:22) buildCheckResult() emits action: "checked" and, when the target differs from CLI_VERSION, adds a warning to run either sentry cli upgrade <target> for a pinned version or bare sentry cli upgrade for channel/latest updates.
🔴 (05:23) executeStandardUpgrade() uses the rolling NIGHTLY_TAG only for the latest nightly when no explicit version was requested; a pinned nightly uses its own release tag.
🔴 (05:23) After curl download, executeStandardUpgrade() runs setup from the temporary binary with install: true, pins SENTRY_INSTALL_DIR through the resolved install directory, sets ensureAuthScopes: !json, honors noAgentSkills, and releases the download lock in finally. Package-manager upgrades instead resolve the new CLI path after installation and run setup with install: false.
🔴 (05:23) Switching a Homebrew/npm/pnpm/Bun/Yarn installation to nightly migrates it to a standalone curl-style binary because nightly builds are distributed only as GitHub release assets. migrateToStandaloneForNightly() downloads via executeUpgrade("curl", ...), installs to determineInstallDir(homedir(), process.env), runs setup with method: "curl" and channel: "nightly", releases the lock in finally, and returns warnings about the old installation potentially shadowing the new binary.
🔴 (05:23) persistChannel() stores the release-channel preference when the channel changed or the positional argument is exactly a channel selector ("nightly" or "stable"). Persistence is deferred until after offline target resolution to avoid clearing the needed cached version.
🔴 (05:23) startChangelogFetch() starts fetchChangelog({channel, fromVersion, toVersion}) in parallel with binary download, returns undefined when offline or already on the target, and never throws because fetch errors are swallowed so they cannot block an upgrade.
🔴 (05:23) The upgrade CLI documents sentry cli upgrade nightly as “Switch to nightly channel and update,” sentry cli upgrade stable as switching back to stable and updating, --check as checking without installation, --force as forcing a redownload, --method npm as overriding installation detection, --offline as using cached patches without network, and --no-agent-skills as skipping agent-skill reinstallation.
🔴 (05:23) The upgrade result waits for the parallel changelog promise after installation and returns action: "upgraded" or "downgraded", the old and target versions, channel, original detected method, force/offline state, migration warnings, and changelog.
🔴 (05:23) Background update checking in packages/cli/src/lib/version-check.ts never throws; errors are caught and reported to Sentry.
🔴 (05:23) Update-notification handling in packages/cli/src/lib/version-check.ts never throws; errors are caught and reported rather than escaping to the CLI caller.
🔴 (05:24) GitHub issue getsentry/cli#1244, titled “toolkit merge: bridge CLI release + dual-source upgrade compatibility,” is an open subtask of master issue getsentry/cli#1248 and a hard prerequisite for importing CLI history into getsentry/sentry-mcp.
🔴 (05:24) The bridge-release requirement is to ship one stable bridge CLI release from getsentry/cli before any CLI history is imported into getsentry/sentry-mcp; it must remain usable before the Toolkit rename, discover Toolkit releases afterward, and preserve upgrades for older binaries through legacy endpoints.
🔴 (05:24) The required ordered upgrade source list for new binaries and the install script is exactly: 1. getsentry/toolkit / ghcr.io/getsentry/toolkit; 2. getsentry/cli / ghcr.io/getsentry/cli.
🔴 (05:24) Ordered-source fallback must proceed to the next source only on HTTP 404. Network and fetch failures are transient errors and must never poison a source.
🔴 (05:24) TypeScript and the generated install script must share one upgrade-source definition, with a check: script that fails if their source lists or ordering diverge.
🔴 (05:24) Because old binaries know only getsentry/cli, every migrated stable CLI release and nightly must be dual-published to Toolkit and legacy CLI endpoints throughout the compatibility window.
🔴 (05:24) Planned dual-source implementation spans src/lib/binary.ts, ghcr.ts, upgrade.ts, and delta-upgrade.ts through UPGRADE_SOURCES; the generated install script must mirror the same ordered fallback.
🔴 (05:24) Delta compatibility must preserve sha256-<binary> / from-version patch chains and cleanup/keep-count parity across both GHCR packages.
🔴 (05:24) The pre-import bridge gate requires: 1. cut the next stable CLI release from getsentry/cli using the release system’s computed version rather than manually pinning one; 2. verify a pre-bridge binary upgrades through getsentry/cli; 3. verify the bridge binary receives a 404 from the not-yet-existing getsentry/toolkit source and falls back to getsentry/cli; 4. verify identical install-script behavior; 5. record the released bridge version before beginning getsentry/cli#1239.
🔴 (05:24) The post-rename compatibility matrix requires: 1. publish one staging CLI release from Toolkit to both repositories; 2. verify a pre-bridge binary upgrades through getsentry/cli; 3. verify bridge and Toolkit-built binaries upgrade through getsentry/toolkit; 4. simulate a Toolkit 404 and verify both new binaries fall back to getsentry/cli; 5. compare release assets, SHA-256 values, GHCR manifests, and delta-chain metadata across both repositories and require exact matches; 6. run the same matrix for the install script and one nightly.
🔴 (05:24) Dual-publishing must continue for at least 2 stable CLI releases and roughly 90 days of nightlies. getsentry/cli must remain writable during that period and may be archived only after telemetry and release evidence show the legacy endpoint is no longer required.

Distillation

Observations