feat(upgrade): add nightly release channel

Add support for a nightly release channel that tracks rolling builds from the
main branch. Users can opt in via the install script or upgrade command, and
the choice is persisted so future bare `sentry cli upgrade` calls use the
same channel automatically.

Changes:
- CI: new `nightly-version` job computes `0.x.y-dev.<unix_ts>` version on
  main pushes; `build-binary` injects it before building; new `publish-nightly`
  job uploads .gz binaries + version.json to a rolling GitHub prerelease tagged
  `nightly` after build+E2E pass
- Install script: `--version nightly` downloads from the nightly release and
  persists the channel via `--channel nightly` passed to `cli setup`
- DB: new `src/lib/db/release-channel.ts` persists channel in the metadata table
- `cli setup`: new `--channel` flag to persist the release channel on install
- `cli upgrade`: `nightly`/`stable` as positional version args switch channels;
  new `--channel` flag as an equivalent alternative; new `--force` flag to
  re-download even when already up to date; auto-migrates brew/npm/pnpm/bun/yarn
  installs to standalone binary when switching to nightly
- Version check: reads persisted channel and checks nightly version.json for
  nightly users; shows "New nightly available:" in notification

Author: BYK

.github/workflows/ci.yml

@@ -11,6 +11,31 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  nightly-version:
+    name: Compute Nightly Version
+    # Only compute a nightly version on direct pushes to main — not on PRs or
+    # release branches. Downstream jobs (build-binary, publish-nightly) check
+    # whether this output is non-empty before acting on it; when this job is
+    # skipped the output is an empty string, so they behave as normal CI runs.
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: package.json
+      - id: version
+        name: Compute version
+        run: |
+          VERSION=$(node -e "
+            const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8'));
+            const ts = Math.floor(Date.now() / 1000);
+            // Replace trailing -dev.<n> suffix with -dev.<unix_seconds>
+            console.log(pkg.version.replace(/-dev\.\d+$/, '-dev.' + ts));
+          ")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
   changes:
     name: Detect Changes
     runs-on: ubuntu-latest
@@ -133,7 +158,7 @@ jobs:
 
   build-binary:
     name: Build Binary (${{ matrix.target }})
-    needs: [lint, test-unit]
+    needs: [lint, test-unit, nightly-version]
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -178,6 +203,19 @@ jobs:
           done
           echo "All install attempts failed"
           exit 1
+      - name: Set nightly version
+        # Inject the computed nightly version into package.json before the build
+        # so it gets baked into the binary. Only runs on main-branch pushes where
+        # nightly-version produced a non-empty output.
+        if: needs.nightly-version.outputs.version != ''
+        shell: bash
+        run: |
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+            pkg.version = process.argv[1];
+            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+          " "${{ needs.nightly-version.outputs.version }}"
       - name: Build
         env:
           SENTRY_CLIENT_ID: ${{ vars.SENTRY_CLIENT_ID }}
@@ -282,17 +320,63 @@ jobs:
           name: gh-pages
           path: gh-pages.zip
 
+  publish-nightly:
+    name: Publish Nightly
+    # Only publish after a successful main-branch build+test. Skipped on PRs
+    # and release branches (nightly-version output will be empty).
+    needs: [nightly-version, build-binary, test-e2e]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download all binary artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: sentry-*
+          path: artifacts
+          merge-multiple: true
+      - name: Create version.json
+        run: |
+          cat > version.json <<EOF
+          {"version":"${{ needs.nightly-version.outputs.version }}","sha":"${{ github.sha }}","date":"$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+          EOF
+      - name: Create or update nightly release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          # Create the release the first time; subsequent runs are a no-op
+          gh release create nightly \
+            --prerelease \
+            --title "Nightly" \
+            --notes "" \
+            2>/dev/null || true
+
+          # Update release notes with the latest version + commit
+          gh release edit nightly \
+            --prerelease \
+            --notes "Latest nightly build from the \`main\` branch.
+
+          **Version:** \`${{ needs.nightly-version.outputs.version }}\`
+          **Commit:** ${{ github.sha }}"
+
+          # Upload/replace all .gz binaries and the version manifest
+          gh release upload nightly --clobber \
+            artifacts/dist-bin/*.gz \
+            version.json
+
   ci-status:
     name: CI Status
     if: always()
-    needs: [changes, check-skill, build-binary, build-npm, build-docs, test-e2e]
+    needs: [changes, check-skill, build-binary, build-npm, build-docs, test-e2e, publish-nightly]
     runs-on: ubuntu-latest
     permissions: {}
     steps:
       - name: Check CI status
         run: |
           # Check for explicit failures or cancellations in all jobs
-          results="${{ needs.check-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }}"
+          results="${{ needs.check-skill.result }} ${{ needs.build-binary.result }} ${{ needs.build-npm.result }} ${{ needs.build-docs.result }} ${{ needs.test-e2e.result }} ${{ needs.publish-nightly.result }}"
           for result in $results; do
             if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
               echo "::error::CI failed"

docs/src/content/docs/commands/cli/upgrade.md

@@ -8,20 +8,37 @@ Self-update the Sentry CLI to the latest or a specific version.
 ## Usage
 
 ```bash
-sentry cli upgrade              # Update to latest version
-sentry cli upgrade 0.5.0        # Update to specific version
+sentry cli upgrade              # Update using the persisted channel (default: stable)
+sentry cli upgrade nightly      # Switch to nightly channel and update
+sentry cli upgrade stable       # Switch back to stable channel and update
+sentry cli upgrade 0.5.0        # Update to a specific stable version
 sentry cli upgrade --check      # Check for updates without installing
+sentry cli upgrade --force      # Force re-download even if already up to date
 sentry cli upgrade --method npm # Force using npm to upgrade
 ```
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `<version>` | Target version to install (defaults to latest) |
+| `<version>` | Target version, or `nightly`/`stable` to switch channel (defaults to latest) |
 | `--check` | Check for updates without installing |
+| `--force` | Re-download even if already on the latest version |
+| `--channel <channel>` | Set release channel: `stable` or `nightly` |
 | `--method <method>` | Force installation method: curl, brew, npm, pnpm, bun, yarn |
 
+## Release Channels
+
+The CLI supports two release channels:
+
+| Channel | Description |
+|---------|-------------|
+| `stable` | Latest stable release (default) |
+| `nightly` | Built from `main`, updated on every commit |
+
+The chosen channel is persisted locally so that subsequent bare `sentry cli upgrade`
+calls use the same channel without requiring a flag.
+
 ## Installation Detection
 
 The CLI auto-detects how it was installed and uses the same method to upgrade:
@@ -35,6 +52,11 @@ The CLI auto-detects how it was installed and uses the same method to upgrade:
 | bun | Globally installed via `bun install -g sentry` |
 | yarn | Globally installed via `yarn global add sentry` |
 
+> **Note:** Nightly builds are only available as standalone binaries (via the curl
+> install method). If you switch to the nightly channel from a package manager or
+> Homebrew install, the CLI will automatically migrate to a standalone binary and
+> warn you about the existing package-manager installation.
+
 ## Examples
 
 ### Check for updates
@@ -46,12 +68,13 @@ sentry cli upgrade --check
 ```
 Installation method: curl
 Current version: 0.4.0
+Channel: stable
 Latest version: 0.5.0
 
 Run 'sentry cli upgrade' to update.
 ```
 
-### Upgrade to latest
+### Upgrade to latest stable
 
 ```bash
 sentry cli upgrade
@@ -60,19 +83,44 @@ sentry cli upgrade
 ```
 Installation method: curl
 Current version: 0.4.0
+Channel: stable
 Latest version: 0.5.0
 
 Upgrading to 0.5.0...
 
 Successfully upgraded to 0.5.0.
 ```
 
+### Switch to nightly channel
+
+```bash
+sentry cli upgrade nightly
+# or equivalently:
+sentry cli upgrade --channel nightly
+```
+
+After switching, bare `sentry cli upgrade` will continue tracking nightly.
+
+### Switch back to stable
+
+```bash
+sentry cli upgrade stable
+# or equivalently:
+sentry cli upgrade --channel stable
+```
+
 ### Upgrade to specific version
 
 ```bash
 sentry cli upgrade 0.5.0
 ```
 
+### Force re-download
+
+```bash
+sentry cli upgrade --force
+```
+
 ### Force installation method
 
 If auto-detection fails or you want to switch installation methods:

docs/src/content/docs/getting-started.mdx

@@ -9,12 +9,21 @@ import PackageManagerCode from "../../components/PackageManagerCode.astro";
 
 ### Install Script
 
-Install the Sentry CLI using the install script:
+Install the latest stable release:
 
 ```bash
 curl https://cli.sentry.dev/install -fsS | bash
 ```
 
+Install the nightly build (built from `main`, updated on every commit):
+
+```bash
+curl https://cli.sentry.dev/install -fsS | bash -s -- --version nightly
+```
+
+The chosen channel is persisted so that `sentry cli upgrade` automatically
+tracks the same channel on future updates.
+
 ### Homebrew
 
 ```bash

install

@@ -13,7 +13,7 @@ Usage: install [options]
 
 Options:
     -h, --help              Display this help message
-    -v, --version <version> Install a specific version (e.g., 0.2.0)
+    -v, --version <version> Install a specific version (e.g., 0.2.0) or "nightly"
         --no-modify-path    Don't modify shell config files (.zshrc, .bashrc, etc.)
         --no-completions    Don't install shell completions
 
@@ -22,6 +22,7 @@ Environment Variables:
 
 Examples:
     curl -fsSL https://cli.sentry.dev/install | bash
+    curl -fsSL https://cli.sentry.dev/install | bash -s -- --version nightly
     curl -fsSL https://cli.sentry.dev/install | bash -s -- --version 0.2.0
     SENTRY_INSTALL_DIR=~/.local/bin curl -fsSL https://cli.sentry.dev/install | bash
 EOF
@@ -80,21 +81,44 @@ if [[ "$os" == "windows" ]]; then
   fi
 fi
 
-# Resolve version
+# Resolve version and download tag.
+#
+# "nightly" is a special value that installs from the rolling nightly prerelease
+# built from the main branch. In this case:
+#   - `version`      holds the human-readable version string (e.g. "0.12.0-dev.1740393600")
+#   - `download_tag` holds the GitHub release tag to download from ("nightly")
+#
+# For stable releases both are the same version string (e.g. "0.5.0").
+channel="stable"
+download_tag=""
+
 if [[ -z "$requested_version" ]]; then
   version=$(curl -fsSL https://api.github.com/repos/getsentry/cli/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
   if [[ -z "$version" ]]; then
     echo -e "${RED}Failed to fetch latest version${NC}"
     exit 1
   fi
+  download_tag="$version"
+elif [[ "$requested_version" == "nightly" ]]; then
+  channel="nightly"
+  download_tag="nightly"
+  version_json=$(curl -fsSL "https://github.com/getsentry/cli/releases/download/nightly/version.json")
+  version=$(echo "$version_json" | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p')
+  if [[ -z "$version" ]]; then
+    echo -e "${RED}Failed to fetch nightly version${NC}"
+    exit 1
+  fi
 else
   version="$requested_version"
+  download_tag="$requested_version"
 fi
 
 # Strip leading 'v' if present (releases use version without 'v' prefix)
 version="${version#v}"
+download_tag="${download_tag#v}"
+
 filename="sentry-${os}-${arch}${suffix}"
-url="https://github.com/getsentry/cli/releases/download/${version}/${filename}"
+url="https://github.com/getsentry/cli/releases/download/${download_tag}/${filename}"
 
 # Download binary to a temp location
 tmpdir="${TMPDIR:-${TMP:-${TEMP:-/tmp}}}"
@@ -119,7 +143,9 @@ chmod +x "$tmp_binary"
 # Delegate installation and configuration to the binary itself.
 # setup --install handles: directory selection, binary placement, PATH,
 # completions, agent skills, and the welcome message.
-setup_args="--install --method curl"
+# --channel persists the release channel so future `sentry cli upgrade`
+# calls track the same channel without requiring a flag.
+setup_args="--install --method curl --channel $channel"
 if [[ "$no_modify_path" == "true" ]]; then
   setup_args="$setup_args --no-modify-path"
 fi

src/commands/cli/setup.ts

@@ -15,6 +15,11 @@ import { buildCommand } from "../../lib/command.js";
 import { installCompletions } from "../../lib/completions.js";
 import { CLI_VERSION } from "../../lib/constants.js";
 import { setInstallInfo } from "../../lib/db/install-info.js";
+import {
+  parseReleaseChannel,
+  type ReleaseChannel,
+  setReleaseChannel,
+} from "../../lib/db/release-channel.js";
 import {
   addToGitHubPath,
   addToPath,
@@ -32,6 +37,7 @@ import {
 type SetupFlags = {
   readonly install: boolean;
   readonly method?: InstallationMethod;
+  readonly channel?: ReleaseChannel;
   readonly "no-modify-path": boolean;
   readonly "no-completions": boolean;
   readonly "no-agent-skills": boolean;
@@ -264,6 +270,13 @@ export const setupCommand = buildCommand({
         placeholder: "method",
         optional: true,
       },
+      channel: {
+        kind: "parsed",
+        parse: parseReleaseChannel,
+        brief: "Release channel to persist (stable or nightly)",
+        placeholder: "channel",
+        optional: true,
+      },
       "no-modify-path": {
         kind: "boolean",
         brief: "Skip PATH modification",
@@ -329,6 +342,14 @@ export const setupCommand = buildCommand({
       }
     }
 
+    // 1b. Persist release channel (set by install script or upgrade --channel)
+    if (flags.channel) {
+      setReleaseChannel(flags.channel);
+      if (!flags.install) {
+        log(`Recorded release channel: ${flags.channel}`);
+      }
+    }
+
     // 2. Handle PATH modification
     if (!flags["no-modify-path"]) {
       await handlePathModification(binaryDir, shell, process.env, log);