Supabase CLI, global vs per project basis

What are we gonna do in this blog post

• Why another supabase CLI post

• Installing supabase CLI globally

• Using supabase per project basis

• Use cases

Why another Supabase CLI post

No doubt there are plenty of “how to install supabase CLI” article there. So the question remains, what motivate me to write up another new one. Let me tell you why. Because at the time of writing this article, I am once again removed the confusion on how to use the supabase CLI. Cause I am not using supabase on a regular basis. It’s one project for one month, then nothing for several months, then one project for another month. In this time-span, I definitely forget how to use supabase CLI. So I have to redo all the steps as well as the searched and ChatGPT prompts in order to get to the knowledge base once again. Also I faced problems with each method every time. So that’s why I decided to write up this post to write down the confusion which I can reference later time. Also whoever stumbles upon the same confusion, they can also reference this post also.

Installing Supabase CLI globally

Macbook with apple silicon chip is my primary working machine, so I will lay out the details for this machine. You can refer to the official documentation for other platforms. I always prefer to install any new SDK with installer, but that is not the case for supabase CLI. So my second preference is to install it with homebrew since I am using Macbook. Homebrew is the package manager for mac and linux. It’s pretty awesome, fortunately supabase does provide installation with homebrew. Here’s how you can do this

brew install supabase/tap/supabase

By running this command homebrew will install supabase after executing following steps

• Auto-update, brew will check for latest versions of tools & formulas

• Fetch tap, brew will pull the Supabase CLI formula from supabase/tap

• Download binary, brew will get the official CLI release for the hosted machine architecture

• Install the CLI, placed it in the Homebrew Cellar & symlinked it

• Setup autocomplete, installed Zsh completions if you're using Zsh

• Cleaned up, Removed unnecessary cache/files post-installation

Here are the logs for the installation, since I previously installed supabase, brew didn’t downloaded it instead it used the cached version.

Adjust how often this is run with HOMEBREW_AUTO_UPDATE_SECS or disable with
HOMEBREW_NO_AUTO_UPDATE. Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
==> Fetching supabase/tap/supabase
==> Downloading https://github.com/supabase/cli/releases/download/v2.30.4/supabase_darwin_arm64.tar.gz
Already downloaded: /Users/rabbykhan/Library/Caches/Homebrew/downloads/1552e950bfacb3ee6937b50ef4ff51a358c61432b2a22a9fd819eb0cc4772b51--supabase_darwin_arm64.tar.gz
==> Installing supabase from supabase/tap
🍺  /opt/homebrew/Cellar/supabase/2.30.4: 9 files, 39.4MB, built in 2 seconds
==> Running `brew cleanup supabase`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions

Problem faced during installation

• supbase CLI requires node version ≥ 16

• Xcode was outdated, first time the installation failed for this reason. Here is the log taken from that attempt. This is the main problem I faced when installing supabase globally.

==> Installing supabase from supabase/tap
Error: Your Xcode (15.4) at /Applications/Xcode.app is too outdated.
Please update to Xcode 16.4 (or delete it).
Xcode can be updated from the App Store.

What Xcode version is needed for supabase CLI

To use the Supabase CLI, particularly when installing it via Homebrew on macOS, we need Xcode Command Line Tools, not necessarily the full Xcode IDE.

For Apple Silicon (M1/M2/M3) Macs, and recent Homebrew updates, we'll typically need:

• Xcode ≥ 15.4

• But some packages (like Supabase CLI) may now require Xcode ≥ 16.4, as you saw in this error:

  "Your Xcode (15.4) at /Applications/Xcode.app is too outdated. Please update to Xcode 16.4 (or delete it)."

Why does Xcode affect installing Supabase CLI with Homebrew?

Short answer, Homebrew uses Xcode command line tools to:

• Build or unpack software packages (like Go-based CLI binaries).

• Compile code if necessary.

• Run certain linking or patching steps behind the scenes.

If the CLI package was compiled with a newer version of macOS SDK, it may fail to install or link unless Xcode is up-to-date.

Long and detailed answer

1. Xcode includes essential developer tools:
   Xcode bundles Apple's command-line tools like clang (the C/C++ compiler), make, git, and other utilities.

2. Homebrew relies on these tools to build software:
   Many Homebrew packages — especially those written in languages like C, C++, or Rust — need to be compiled from source during installation.

3. Supabase CLI is written in Go:
   While Go usually provides prebuilt binaries, sometimes Homebrew formulas still rely on Xcode’s tools for building, linking, or packaging.

4. Version compatibility:
   Newer Homebrew formulas or dependencies often require a minimum Xcode version (in your case, 16.4+) to ensure the build tools support all needed features.

5. If Xcode is missing or outdated:

   • The build will fail, as the necessary compilers or SDKs are not available or are incompatible.

   • Homebrew will refuse to proceed and show an error like you saw.

Using Supabase on a project-by-project basis

Now lets dive how we can use the CLI on project-by-project basis. What does that actually means? It means that Supabase CLI will be available inside the project folder only, you will not be using it outside of the project folder. So all the commands for Supabase CLI will be valid and executable for that project only. Lets dive into action, it’s better to show than just throwing theory.

• Create a sample project directory where you wanna install and use supabase CLI functionality and potentially setup a supabase project.

• Go to the project folder directory

• Run this command

    npm install supabase --save-dev
  

  If you are like me and want to use yarn then use the following command

    yarn add -D supabase
  

• Since we just created the project folder and nothing was there, it will install all the necessary modules and the package.json and also the lock file. To be specific it will create package-lock.json if used npm and yarn.lock if used yarn.

• Now check the Supabase CLI version by using the command

    npx supabase --version # this will work for both npm and yarn
    yarn supabase --version # this will work only if supabase is installed with yarn
  
    # running the above command returns following for my case
    2.30.4
  

  This is actually the catch. So when installed globally there is no need to use the prefix (npx) , we can just type supabase —version and it will return us the version. But this is not the case if we wanna use the supabase CLI for a particular project only. This is the main difference on how to use supabase CLI inside the terminal. For local version you have to include the prefix when executing supabase command but such is not required for the global version.

Use cases

• Project wise option is better because you can use different login and account for different project . This is specially true if you are freelancer by heart and dealing with multiple projects from multiple clients. In that case this is the must have weapon in your arsenal. Now if you are using supabase global then you have to use supabase login every time when you switch project. This is a pain in the ass when you are dealing with multiple projects from multiple clients

• Supabase global CLI is useful when you are experimenting the supabase and want to get a feel about all the features and functionalities supabase offers. It will keep you free from having headaches about how to manage all those cli things. You just installed it once and then you are good to go.

According to me, supabase project basis setup is the winner because of the flexibility it provides. But it takes a little bit of time to grasp that there are two different ways. I write this up so that I can reference it later when I am having similar confusion once again and for those who are having the same type of confusion. That’s it for today. See you around in another piece of article.