From 84268aa810f23bba46eedd40aaa1f1d9d45b8454 Mon Sep 17 00:00:00 2001
From: Andrew Valleteau <avallete@users.noreply.github.com>
Date: Mon, 11 May 2026 16:43:00 +0200
Subject: [PATCH] docs(cli): document beta channel install and link SASL
 troubleshooting (#45734)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES/NO

## What kind of change does this PR introduce?

Bug fix, feature, docs update, ...

## What is the current behavior?

Please link any relevant issues here.

## What is the new behavior?

Feel free to include screenshots if it includes visual changes.

## Additional context

Add any other context or screenshots.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added Beta channel section documenting pre-release Supabase CLI
installation for macOS, Windows, Linux, and npm.
* Updated CLI update instructions with beta-specific commands for
Homebrew, Scoop, and npm.
* Enhanced troubleshooting guide with reference to beta channel
documentation.

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/45734)

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: avallete <8771783+avallete@users.noreply.github.com>
---
 .../local-development/cli/getting-started.mdx | 82 +++++++++++++++++++
 ...-or-invalid-scram-server-final-message.mdx |  2 +-
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/apps/docs/content/guides/local-development/cli/getting-started.mdx b/apps/docs/content/guides/local-development/cli/getting-started.mdx
index a14bbf4b4f1..f3675c13895 100644
--- a/apps/docs/content/guides/local-development/cli/getting-started.mdx
+++ b/apps/docs/content/guides/local-development/cli/getting-started.mdx
@@ -97,6 +97,64 @@ Global installation using `npm install -g supabase` is not supported. For global
 </TabPanel>
 </Tabs>
 
+## Beta channel
+
+Pre-release CLI builds ship from the development branch (`X.Y.Z-beta.N` versions). Use the npm `beta` dist-tag, or install `supabase-beta` via Homebrew / Scoop (separate packages from stable).
+
+<Tabs
+  scrollable
+  size="small"
+  type="underlined"
+  defaultActiveId="npm"
+  queryGroup="platform"
+>
+<TabPanel id="macos" label="macOS">
+
+```sh
+brew install supabase/tap/supabase-beta
+brew link --overwrite supabase-beta
+```
+
+</TabPanel>
+<TabPanel id="windows" label="Windows">
+
+```powershell
+scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
+scoop install supabase-beta
+```
+
+</TabPanel>
+<TabPanel id="linux" label="Linux">
+
+#### Homebrew
+
+```sh
+brew install supabase/tap/supabase-beta
+brew link --overwrite supabase-beta
+```
+
+#### Linux packages
+
+Beta builds are attached to [GitHub pre-releases](https://github.com/supabase/cli/releases). Download the `.apk`, `.deb`, or `.rpm` for your platform and install with the same commands as [Linux packages](#linux-packages) above.
+
+</TabPanel>
+<TabPanel id="npm" label="nodejs">
+
+Install as a dev dependency:
+
+```sh
+npm install supabase@beta --save-dev
+```
+
+Or run without installing:
+
+```sh
+npx supabase@beta --help
+```
+
+</TabPanel>
+</Tabs>
+
 ## Updating the Supabase CLI
 
 When a new [version](https://github.com/supabase/cli/releases) is released, you can update the CLI using the same methods.
@@ -114,6 +172,12 @@ When a new [version](https://github.com/supabase/cli/releases) is released, you
 brew upgrade supabase
 ```
 
+Beta channel:
+
+```sh
+brew upgrade supabase-beta
+```
+
 </TabPanel>
 <TabPanel id="windows" label="Windows">
 
@@ -121,6 +185,12 @@ brew upgrade supabase
 scoop update supabase
 ```
 
+Beta channel:
+
+```powershell
+scoop update supabase-beta
+```
+
 </TabPanel>
 <TabPanel id="linux" label="Linux">
 
@@ -130,6 +200,12 @@ scoop update supabase
 brew upgrade supabase
 ```
 
+Beta channel:
+
+```sh
+brew upgrade supabase-beta
+```
+
 #### Linux package manager
 
 1. Download the latest package from the [Supabase CLI releases page](https://github.com/supabase/cli/releases/latest)
@@ -147,6 +223,12 @@ If you have installed the CLI as dev dependency via [npm](https://www.npmjs.com/
 npm update supabase --save-dev
 ```
 
+Beta channel (`supabase@beta`):
+
+```sh
+npm update supabase@beta --save-dev
+```
+
 </TabPanel>
 </Tabs>
 
diff --git a/apps/docs/content/troubleshooting/supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message.mdx b/apps/docs/content/troubleshooting/supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message.mdx
index 61b57decaf4..848803365ec 100644
--- a/apps/docs/content/troubleshooting/supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message.mdx
+++ b/apps/docs/content/troubleshooting/supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message.mdx
@@ -24,7 +24,7 @@ This typically indicates an authentication failure where the database connection
     ```
 
 3.  **Skip the Pooler and connect directly to the database with the Supabase CLI (Requires IPv6):**
-    - If your network supports IPv6, you can use the beta CLI version with the `--skip-pooler` flag to bypass the connection pooler to avoid this particular issue.
+    - If your network supports IPv6, you can use the beta CLI version with the `--skip-pooler` flag to bypass the connection pooler to avoid this particular issue. Install options are documented under [Beta channel](/docs/guides/local-development/cli/getting-started#beta-channel) in the CLI getting started guide.
 
     ```bash
     npx supabase@beta link --skip-pooler