feat(release): add Homebrew install support (#277)

Closes #228

## What

Adds `brew install getsentry/tools/sentry` as a supported install
method.

## Changes

**`.craft.yml`** — new `brew` target that publishes `Formula/sentry.rb`
to the `getsentry/homebrew-tools` tap on each stable release. Uses
`includeNames` to filter to the 4 macOS/Linux binaries only (no `.gz`,
no Windows, no npm tarball). Checksum template keys are the raw
filenames since they contain no dots or version strings.

**`src/lib/upgrade.ts`** — adds `"brew"` as an `InstallationMethod`.
Detection checks for `/Cellar/` in `process.execPath` (works for both
Apple Silicon and Intel Homebrew prefixes). Upgrade runs `brew upgrade
getsentry/tools/sentry`. Version pinning is intentionally unsupported
since Homebrew manages versioning through the formula.

**Docs** — `getting-started.mdx` and `commands/cli/upgrade.md` updated
to document the new install and upgrade paths.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

.craft.yml

@@ -17,3 +17,51 @@ targets:
   - name: npm
   - name: github
   - name: gh-pages
+  - name: brew
+    tap: getsentry/tools
+    formula: sentry
+    path: Formula
+    includeNames: '/^sentry-(darwin|linux)-(arm64|x64)\.gz$/'
+    template: |
+      class Sentry < Formula
+        desc "Sentry command-line tool for error monitoring and debugging"
+        homepage "https://cli.sentry.dev"
+        version "{{version}}"
+        license "FSL-1.1-MIT"
+
+        if OS.mac?
+          if Hardware::CPU.arm?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-darwin-arm64.gz"
+            sha256 "{{checksums.sentry-darwin-arm64__gz}}"
+          elsif Hardware::CPU.intel?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-darwin-x64.gz"
+            sha256 "{{checksums.sentry-darwin-x64__gz}}"
+          else
+            raise "Unsupported macOS CPU architecture: #{Hardware::CPU.type}"
+          end
+        elsif OS.linux?
+          if Hardware::CPU.arm? && Hardware::CPU.is_64_bit?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-linux-arm64.gz"
+            sha256 "{{checksums.sentry-linux-arm64__gz}}"
+          elsif Hardware::CPU.intel? && Hardware::CPU.is_64_bit?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-linux-x64.gz"
+            sha256 "{{checksums.sentry-linux-x64__gz}}"
+          else
+            raise "Unsupported Linux CPU architecture: #{Hardware::CPU.type} (only 64-bit arm and x86_64 are supported)"
+          end
+        else
+          raise "Unsupported operating system"
+        end
+
+        def install
+          bin.install Dir["sentry-*"].first => "sentry"
+        end
+
+        def post_install
+          system bin/"sentry", "cli", "setup", "--method", "brew", "--no-modify-path"
+        end
+
+        test do
+          assert_match version.to_s, shell_output("#{bin}/sentry --version").chomp
+        end
+      end

README.md

@@ -22,6 +22,12 @@
 curl -fsSL https://cli.sentry.dev/install | bash
 ```
 
+### Homebrew
+
+```bash
+brew install getsentry/tools/sentry
+```
+
 ### Package Managers
 
 ```bash

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

@@ -20,7 +20,7 @@ sentry cli upgrade --method npm # Force using npm to upgrade
 |--------|-------------|
 | `<version>` | Target version to install (defaults to latest) |
 | `--check` | Check for updates without installing |
-| `--method <method>` | Force installation method: curl, npm, pnpm, bun, yarn |
+| `--method <method>` | Force installation method: curl, brew, npm, pnpm, bun, yarn |
 
 ## Installation Detection
 
@@ -29,6 +29,7 @@ The CLI auto-detects how it was installed and uses the same method to upgrade:
 | Method | Detection |
 |--------|-----------|
 | curl | Binary located in `~/.sentry/bin` (installed via cli.sentry.dev) |
+| brew | Binary located in a Homebrew Cellar (installed via `brew install getsentry/tools/sentry`) |
 | npm | Globally installed via `npm install -g sentry` |
 | pnpm | Globally installed via `pnpm add -g sentry` |
 | bun | Globally installed via `bun install -g sentry` |

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

@@ -15,6 +15,12 @@ Install the Sentry CLI using the install script:
 curl https://cli.sentry.dev/install -fsS | bash
 ```
 
+### Homebrew
+
+```bash
+brew install getsentry/tools/sentry
+```
+
 ### Package Managers
 
 Install globally with your preferred package manager:

docs/src/content/docs/index.mdx

@@ -22,6 +22,7 @@ export const base = import.meta.env.BASE_URL.endsWith('/') ? import.meta.env.BAS
 <div class="hero-command">
 <InstallSelector options={[
   { label: "curl", command: "curl https://cli.sentry.dev/install -fsS | bash" },
+  { label: "brew", command: "brew install getsentry/tools/sentry" },
   { label: "npx", command: "npx sentry@latest" },
   { label: "npm", command: "npm install -g sentry" },
   { label: "pnpm", command: "pnpm add -g sentry" },

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -15,6 +15,7 @@ The CLI must be installed and authenticated before use.
 
 ```bash
 curl https://cli.sentry.dev/install -fsS | bash
+brew install getsentry/tools/sentry
 
 # Or install via npm/pnpm/bun
 npm install -g sentry
@@ -435,7 +436,7 @@ Update the Sentry CLI to the latest version
 
 **Flags:**
 - `--check - Check for updates without installing`
-- `--method <value> - Installation method to use (curl, npm, pnpm, bun, yarn)`
+- `--method <value> - Installation method to use (curl, brew, npm, pnpm, bun, yarn)`
 
 ### Repo
 

src/commands/cli/upgrade.ts

@@ -157,7 +157,7 @@ export const upgradeCommand = buildCommand({
       method: {
         kind: "parsed",
         parse: parseInstallationMethod,
-        brief: "Installation method to use (curl, npm, pnpm, bun, yarn)",
+        brief: "Installation method to use (curl, brew, npm, pnpm, bun, yarn)",
         optional: true,
         placeholder: "method",
       },
@@ -177,6 +177,15 @@ export const upgradeCommand = buildCommand({
       throw new UpgradeError("unknown_method");
     }
 
+    // Homebrew manages versioning through the formula in the tap — the installed
+    // version is always whatever the formula specifies, not an arbitrary release.
+    if (method === "brew" && version) {
+      throw new UpgradeError(
+        "unsupported_operation",
+        "Homebrew does not support installing a specific version. Run 'brew upgrade getsentry/tools/sentry' to upgrade to the latest formula version."
+      );
+    }
+
     stdout.write(`Installation method: ${method}\n`);
     stdout.write(`Current version: ${CLI_VERSION}\n`);
 
@@ -213,10 +222,9 @@ export const upgradeCommand = buildCommand({
       } finally {
         releaseLock(downloadResult.lockPath);
       }
-    } else {
+    } else if (method !== "brew") {
       // Package manager: binary already in place, just run setup.
-      // Always use execPath — storedInfo?.path could reference a stale
-      // binary from a different installation method.
+      // Skip brew — Homebrew's post_install hook already runs setup.
       await runSetupOnNewBinary(this.process.execPath, method, false);
     }
 

src/lib/errors.ts

@@ -232,6 +232,7 @@ export class DeviceFlowError extends CliError {
 
 export type UpgradeErrorReason =
   | "unknown_method"
+  | "unsupported_operation"
   | "network_error"
   | "execution_failed"
   | "version_not_found";
@@ -249,6 +250,8 @@ export class UpgradeError extends CliError {
     const defaultMessages: Record<UpgradeErrorReason, string> = {
       unknown_method:
         "Could not detect installation method. Use --method to specify.",
+      unsupported_operation:
+        "This operation is not supported for this installation method.",
       network_error: "Failed to fetch version information.",
       execution_failed: "Upgrade command failed.",
       version_not_found: "The specified version was not found.",

src/lib/upgrade.ts

@@ -7,7 +7,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { chmodSync, unlinkSync } from "node:fs";
+import { chmodSync, realpathSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, sep } from "node:path";
 import {
@@ -29,6 +29,7 @@ import { UpgradeError } from "./errors.js";
 
 export type InstallationMethod =
   | "curl"
+  | "brew"
   | "npm"
   | "pnpm"
   | "bun"
@@ -162,6 +163,26 @@ async function isInstalledWith(pm: PackageManager): Promise<boolean> {
   }
 }
 
+/**
+ * Detect if the CLI binary is running from a Homebrew Cellar.
+ *
+ * Homebrew places the real binary deep in the Cellar
+ * (e.g. `/opt/homebrew/Cellar/sentry/1.2.3/bin/sentry`) and exposes it
+ * via a symlink at the prefix bin dir (e.g. `/opt/homebrew/bin/sentry`).
+ * `process.execPath` typically reflects the symlink, not the realpath, so
+ * we resolve symlinks first before checking for `/Cellar/`. Falls back to
+ * the unresolved path if `realpathSync` throws (e.g. binary was deleted).
+ */
+function isHomebrewInstall(): boolean {
+  let execPath = process.execPath;
+  try {
+    execPath = realpathSync(execPath);
+  } catch {
+    // Binary may have been deleted or moved; use the original path
+  }
+  return execPath.includes("/Cellar/");
+}
+
 /**
  * Legacy detection for existing installs that don't have stored install info.
  * Checks known curl install paths and package managers.
@@ -199,7 +220,14 @@ async function detectLegacyInstallationMethod(): Promise<InstallationMethod> {
  * @returns Detected installation method, or "unknown" if unable to determine
  */
 export async function detectInstallationMethod(): Promise<InstallationMethod> {
-  // 1. Check stored info (fast path)
+  // Always check for Homebrew first — the stored install info may be stale
+  // (e.g. user previously had a curl install recorded, then switched to
+  // Homebrew). The realpath check is cheap and authoritative.
+  if (isHomebrewInstall()) {
+    return "brew";
+  }
+
+  // 1. Check stored info (fast path for non-Homebrew installs)
   const stored = getInstallInfo();
   if (stored?.method) {
     return stored.method;
@@ -289,7 +317,7 @@ export async function fetchLatestFromNpm(): Promise<string> {
 
 /**
  * Fetch the latest available version based on installation method.
- * curl installations check GitHub releases; package managers check npm.
+ * curl and brew installations check GitHub releases; package managers check npm.
  *
  * @param method - How the CLI was installed
  * @returns Latest version string (without 'v' prefix)
@@ -298,7 +326,9 @@ export async function fetchLatestFromNpm(): Promise<string> {
 export function fetchLatestVersion(
   method: InstallationMethod
 ): Promise<string> {
-  return method === "curl" ? fetchLatestFromGitHub() : fetchLatestFromNpm();
+  return method === "curl" || method === "brew"
+    ? fetchLatestFromGitHub()
+    : fetchLatestFromNpm();
 }
 
 /**
@@ -314,7 +344,7 @@ export async function versionExists(
   method: InstallationMethod,
   version: string
 ): Promise<boolean> {
-  if (method === "curl") {
+  if (method === "curl" || method === "brew") {
     const response = await fetchWithUpgradeError(
       `${GITHUB_RELEASES_URL}/tags/${version}`,
       { method: "HEAD", headers: getGitHubHeaders() },
@@ -453,6 +483,43 @@ export async function downloadBinaryToTemp(
   }
 }
 
+/**
+ * Execute upgrade via Homebrew.
+ *
+ * Runs `brew upgrade getsentry/tools/sentry` which fetches the latest
+ * formula from the tap and installs the new version. The version argument
+ * is intentionally ignored: Homebrew manages versioning through the formula
+ * file in the tap and does not support pinning to an arbitrary release.
+ *
+ * @throws {UpgradeError} When brew upgrade fails
+ */
+function executeUpgradeHomebrew(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("brew", ["upgrade", "getsentry/tools/sentry"], {
+      stdio: "inherit",
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(
+          new UpgradeError(
+            "execution_failed",
+            `brew upgrade failed with exit code ${code}`
+          )
+        );
+      }
+    });
+
+    proc.on("error", (err) => {
+      reject(
+        new UpgradeError("execution_failed", `brew failed: ${err.message}`)
+      );
+    });
+  });
+}
+
 /**
  * Execute upgrade via package manager global install.
  *
@@ -516,6 +583,9 @@ export async function executeUpgrade(
   switch (method) {
     case "curl":
       return downloadBinaryToTemp(version);
+    case "brew":
+      await executeUpgradeHomebrew();
+      return null;
     case "npm":
     case "pnpm":
     case "bun":
@@ -530,6 +600,7 @@ export async function executeUpgrade(
 /** Valid methods that can be specified via --method flag */
 const VALID_METHODS: InstallationMethod[] = [
   "curl",
+  "brew",
   "npm",
   "pnpm",
   "bun",

test/commands/cli/upgrade.test.ts

@@ -216,6 +216,39 @@ describe("sentry cli upgrade", () => {
     });
   });
 
+  describe("brew method", () => {
+    test("errors immediately when specific version requested with brew", async () => {
+      // No fetch mock needed — error is thrown before any network call
+      const { context, output, errors } = createMockContext({
+        homeDir: testDir,
+      });
+
+      await run(app, ["cli", "upgrade", "--method", "brew", "1.2.3"], context);
+
+      const allOutput = [...output, ...errors].join("");
+      expect(allOutput).toContain(
+        "Homebrew does not support installing a specific version"
+      );
+    });
+
+    test("check mode works for brew method", async () => {
+      mockGitHubVersion("99.99.99");
+
+      const { context, output } = createMockContext({ homeDir: testDir });
+
+      await run(
+        app,
+        ["cli", "upgrade", "--check", "--method", "brew"],
+        context
+      );
+
+      const combined = output.join("");
+      expect(combined).toContain("Installation method: brew");
+      expect(combined).toContain("Latest version: 99.99.99");
+      expect(combined).toContain("Run 'sentry cli upgrade' to update.");
+    });
+  });
+
   describe("version validation", () => {
     test("reports error for non-existent version", async () => {
       // Mock: latest is 99.99.99, but 0.0.1 doesn't exist