feat(release): add Homebrew install support

- Add brew target to .craft.yml to publish Formula/sentry.rb to
  getsentry/homebrew-tools tap on each stable release
- Detect Homebrew installs (binary under /Cellar/) and run
  `brew upgrade getsentry/tools/sentry` for self-upgrades
- Add brew to VALID_METHODS and fetchLatestVersion/versionExists
  routing (uses GitHub releases, same as curl)
- Document `brew install getsentry/tools/sentry` in getting-started
  and cli-upgrade docs

Closes #228

Author: BYK

.craft.yml

@@ -17,3 +17,43 @@ targets:
   - name: npm
   - name: github
   - name: gh-pages
+  - name: brew
+    tap: getsentry/tools
+    formula: sentry
+    path: Formula
+    includeNames: '/^sentry-(darwin|linux)-(arm64|x64)$/'
+    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"
+            sha256 "{{checksums.sentry-darwin-arm64}}"
+          elsif Hardware::CPU.intel?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-darwin-x64"
+            sha256 "{{checksums.sentry-darwin-x64}}"
+          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"
+            sha256 "{{checksums.sentry-linux-arm64}}"
+          elsif Hardware::CPU.intel? && Hardware::CPU.is_64_bit?
+            url "https://github.com/getsentry/cli/releases/download/{{version}}/sentry-linux-x64"
+            sha256 "{{checksums.sentry-linux-x64}}"
+          end
+        else
+          raise "Unsupported operating system"
+        end
+
+        def install
+          bin.install Dir["sentry-*"].first => "sentry"
+        end
+
+        test do
+          assert_match version.to_s, shell_output("#{bin}/sentry --version").chomp
+        end
+      end

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:

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",
       },

src/lib/upgrade.ts

@@ -29,6 +29,7 @@ import { UpgradeError } from "./errors.js";
 
 export type InstallationMethod =
   | "curl"
+  | "brew"
   | "npm"
   | "pnpm"
   | "bun"
@@ -162,13 +163,31 @@ async function isInstalledWith(pm: PackageManager): Promise<boolean> {
   }
 }
 
+/**
+ * Detect if the CLI binary is running from a Homebrew Cellar.
+ *
+ * Homebrew installs binaries as symlinks into the Cellar directory
+ * (e.g. `/opt/homebrew/Cellar/sentry/1.2.3/bin/sentry` or
+ * `/usr/local/Cellar/sentry/1.2.3/bin/sentry`). Checking for `/Cellar/`
+ * in the resolved exec path is a reliable heuristic that works on both
+ * Apple Silicon (`/opt/homebrew`) and Intel Macs (`/usr/local`).
+ */
+function isHomebrewInstall(): boolean {
+  return process.execPath.includes("/Cellar/");
+}
+
 /**
  * Legacy detection for existing installs that don't have stored install info.
  * Checks known curl install paths and package managers.
  *
  * @returns Detected installation method, or "unknown" if unable to determine
  */
 async function detectLegacyInstallationMethod(): Promise<InstallationMethod> {
+  // Check for Homebrew Cellar path before curl — both may match known bin dirs
+  if (isHomebrewInstall()) {
+    return "brew";
+  }
+
   // Check known curl install paths
   for (const dir of KNOWN_CURL_PATHS) {
     if (process.execPath.startsWith(dir)) {
@@ -289,7 +308,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 +317,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 +335,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 +474,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 +574,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 +591,7 @@ export async function executeUpgrade(
 /** Valid methods that can be specified via --method flag */
 const VALID_METHODS: InstallationMethod[] = [
   "curl",
+  "brew",
   "npm",
   "pnpm",
   "bun",