diff --git a/.github/workflows/cli-release.yml b/.github/workflows/cli-release.yml
index 873e38d..8bd537f 100644
--- a/.github/workflows/cli-release.yml
+++ b/.github/workflows/cli-release.yml
@@ -70,8 +70,9 @@ jobs:
             **macOS/Linux (Homebrew):**
             ```bash
             brew tap starkSV/msdl
-            brew install msdl
+            brew install msdl-cli
             ```
+            (formula is `msdl-cli`, not `msdl` -- homebrew/core has an unrelated package named `msdl`; the installed command is still just `msdl`)
 
             **macOS/Linux (no Homebrew):**
             ```bash
diff --git a/README.md b/README.md
index 87a730a..e88c0fc 100644
--- a/README.md
+++ b/README.md
@@ -66,8 +66,9 @@ winget install starkSV.msdl
 **macOS / Linux (Homebrew):**
 ```bash
 brew tap starkSV/msdl
-brew install msdl
+brew install msdl-cli
 ```
+(the formula is named `msdl-cli`, not `msdl` — `homebrew/core` already has an unrelated package called `msdl`; the installed command is still just `msdl`)
 
 **macOS / Linux (no Homebrew):**
 ```bash
diff --git a/frontend/src/components/CliHandoff.tsx b/frontend/src/components/CliHandoff.tsx
index 0c4cd26..dda9df8 100644
--- a/frontend/src/components/CliHandoff.tsx
+++ b/frontend/src/components/CliHandoff.tsx
@@ -25,7 +25,7 @@ function InstallSteps() {
   }
 
   function handleBrewCopy() {
-    navigator.clipboard.writeText('brew tap starkSV/msdl && brew install msdl')
+    navigator.clipboard.writeText('brew tap starkSV/msdl && brew install msdl-cli')
     setBrewCopied(true)
     setTimeout(() => setBrewCopied(false), 2000)
   }
@@ -57,7 +57,7 @@ function InstallSteps() {
           <span className="text-[10px] px-1.5 py-0.5 rounded border border-emerald-500/20 text-emerald-600 font-mono">recommended</span>
         </div>
         <div className="flex items-center justify-between gap-2 rounded bg-black/30 px-3 py-2">
-          <code className="text-[12px] font-mono text-zinc-300">brew tap starkSV/msdl && brew install msdl</code>
+          <code className="text-[12px] font-mono text-zinc-300">brew tap starkSV/msdl && brew install msdl-cli</code>
           <button onClick={handleBrewCopy} className="flex-shrink-0 text-zinc-500 hover:text-white transition-colors">
             {brewCopied ? <Check size={12} className="text-green-400" /> : <Copy size={12} />}
           </button>
diff --git a/frontend/src/pages/CliPage.tsx b/frontend/src/pages/CliPage.tsx
index 7495d9b..d0b7a0f 100644
--- a/frontend/src/pages/CliPage.tsx
+++ b/frontend/src/pages/CliPage.tsx
@@ -113,7 +113,8 @@ export default function CliPage() {
                 <span className="text-[11px] font-mono font-semibold tracking-widest uppercase text-emerald-500">macOS / Linux · Homebrew</span>
                 <span className="text-[10px] px-1.5 py-0.5 rounded border border-emerald-500/20 text-emerald-600 font-mono">recommended</span>
               </div>
-              <CodeBlock code="brew tap starkSV/msdl && brew install msdl" />
+              <CodeBlock code="brew tap starkSV/msdl && brew install msdl-cli" />
+              <p className="text-[11px] text-zinc-600">Formula is <code className="text-zinc-500">msdl-cli</code>, not <code className="text-zinc-500">msdl</code> — homebrew/core has an unrelated package named msdl. The installed command is still just <code className="text-zinc-500">msdl</code>.</p>
             </div>
 
             {/* No Homebrew — curl installer */}