When you’re building a modern web application, connecting a powerful backend like Supabase to a flexible frontend platform is a critical step. To do this smoothly, you need to get the hang of a few key identifiers, the most important being the supabase project-ref. Think of it as your project’s unique address in the Supabase universe.
Whether you’re setting up a local development environment, configuring deployment pipelines, or integrating with a visual builder like WeWeb, understanding your supabase project-ref is essential. It helps you avoid common errors and ensures your frontend can communicate with the right backend. Let’s break down everything you need to know.
What Is a Supabase Project Ref (And Where Do You Find It)?
A supabase project-ref (often called a Project ID or Project Reference) is the unique alphanumeric string that Supabase assigns to every project you create. It’s the primary identifier used to distinguish your project from all others on the platform. These terms, Project ID and Project Reference, are used interchangeably, but they all point to the same unique code.
This reference is a core part of your project’s URL and API endpoints, especially if your frontend queries a GraphQL layer via WeWeb’s GraphQL integration. For instance, in an API URL like https://abcdefghijklmnopqrst.supabase.co, the abcdefghijklmnopqrst part is your project’s unique reference. Every API request your application makes uses this identifier to find and interact with your specific backend instance.
How to get your project ID from the dashboard URL:
The simplest way to find your supabase project-ref is right in your browser’s address bar.
- Log in to your Supabase account.
- Navigate to your project’s dashboard.
- Look at the URL. It will look something like this:
https://supabase.com/dashboard/project/<project-ref>
The part of the URL labeled <project-ref> is the identifier you need. You can just copy and paste it directly from there.
The Anatomy of a Supabase Project Ref
Supabase project references follow a strict and consistent format, which is important to recognize, especially when troubleshooting.
- Length: A
supabase project-refis always exactly 20 characters long. - Characters: It consists of lowercase letters (a to z) and sometimes numbers (0 to 9). You will never find uppercase letters or special symbols in a valid project ref.
This format is strictly enforced by Supabase tools. If you try to use an identifier that doesn’t match this pattern, the Supabase CLI will give you an error. A common error message explicitly states the rule, saying something like, “Invalid project ref format. Must be like abcdefghijklmnopqrst.” This is a clear sign that the string you provided is either the wrong length or contains invalid characters.
Using Your Supabase Project-Ref with the CLI
The Command Line Interface (CLI) is where your supabase project-ref becomes incredibly useful for managing your project programmatically.
Linking Your Local Project: supabase link --project-ref
The supabase link command is how you connect your local project directory to a remote Supabase project. This link tells the CLI which backend in the cloud your local code corresponds to. To create this connection, you must specify which project to link to.
This is where the --project-ref flag comes in. The command is not meant to be run by itself; you must include your project’s reference.
Example Command:
supabase link --project-ref your20characterprojectref
After running this command, the CLI saves your supabase project-ref in a local configuration file. This means you won’t have to specify it again for other commands like supabase db pull or supabase db push, as the CLI now knows which project you’re working on. If you’re starting from scratch on the UI, you can speed things up with a WeWeb template.
The --project-ref Flag Explained
The --project-ref flag is a command line option you can add to many Supabase CLI commands. It manually tells the CLI which Supabase project to target for that specific action.
If you haven’t linked your project or you’re working in an environment where linking isn’t practical (like an automated script), this flag is your best friend. It removes any ambiguity about which project a command should affect. For certain commands like supabase link, the CLI requires the --project-ref flag. If you forget it, you will see an error message stating that a required flag was not set.
Managing Multiple Environments Like a Pro
For any serious application, you’ll likely have at least two environments: a staging environment for testing and a production environment for live users. The best practice is to create a separate Supabase project for each.
Using Environment Variables: SUPABASE_PROJECT_ID
In automated environments like CI/CD pipelines, you can’t interactively run supabase link. Instead, you use environment variables. The Supabase CLI will automatically detect the SUPABASE_PROJECT_ID environment variable if it’s set.
By setting this variable, you provide the project context for all subsequent CLI commands in that session. This is the standard way to work with the CLI in non interactive settings. According to Supabase’s documentation, running the CLI in a CI/CD pipeline requires three key environment variables:
SUPABASE_ACCESS_TOKENSUPABASE_DB_PASSWORDSUPABASE_PROJECT_ID
Configuring Production and Staging Project Refs
To manage your staging and production environments effectively, you should use distinct project references for each.
- Create Two Projects: Create one Supabase project for staging and another for production. Each will have its own unique
supabase project-ref. - Store IDs Securely: Store these two project refs as secrets in your deployment environment. A common naming convention is
STAGING_PROJECT_IDandPRODUCTION_PROJECT_ID. - Use in Workflows: In your deployment scripts, you can load the appropriate ID into the
SUPABASE_PROJECT_IDvariable depending on the target environment. For example, a deployment to your main branch would usePRODUCTION_PROJECT_ID, while a deployment to a develop branch would useSTAGING_PROJECT_ID.
This professional workflow is essential for building reliable applications, and it’s something you can manage perfectly when you build your application on WeWeb, which also supports distinct staging and production environments for your frontend. Teams and agencies can streamline this setup in WeWeb for Agencies.
How to Fix the “Missing Project Ref” Error
Sooner or later, you’ll probably run into an error related to a missing supabase project-ref. It’s one of the most common issues for developers new to the Supabase CLI. The error usually looks like one of these two messages:
required flag(s) "project-ref" not setError: Invalid project ref format. Must be like 'abcdefghijklmnopqrst'.
Both messages mean the same thing: the CLI doesn’t know which project you want to work on. Here’s how to fix it.
- Add the
--project-refFlag: The quickest fix is to simply add the flag to the command you just ran. For example:supabase link --project-ref yourprojectrefhere. - Link Your Project First: If you plan on running multiple commands, run
supabase link --project-ref <your-ref>once. This will save the context, and you won’t need the flag for future commands in that directory. - Check Your Environment Variables: If you’re in a CI/CD environment, ensure the
SUPABASE_PROJECT_IDenvironment variable is correctly set and available to the script. - Verify the Format: If you provided the ref but still got an error, double check that you copied the entire 20 character string correctly, with no extra spaces or typos.
By following these steps, you can quickly resolve the error and get back to building. For step‑by‑step lessons on building frontends that connect to Supabase, visit WeWeb Academy. Building powerful, production‑grade applications requires getting these details right, and platforms like WeWeb are designed for professionals who need this level of control over their backend and deployment workflows. Explore real‑world builds in the WeWeb Showcase.
Frequently Asked Questions (FAQ)
What’s the difference between a Supabase Project ID and a Project Ref?
There is no difference. Supabase Project ID, Project Reference, and supabase project-ref all refer to the same unique 20 character string that identifies your project.
Is the supabase project-ref a secret?
No, it is not considered a secret. While you shouldn’t publicize it unnecessarily, it is a public identifier. To access your project’s data, a malicious actor would still need your secret API keys or an access token. For compliance details on how WeWeb handles data, review our Data Processing Agreement.
Can I change my supabase project-ref?
No, you cannot change a project’s reference after it has been created. It is permanently assigned to the project. If you need a different reference, you would have to create a new project.
Where can I find my supabase project-ref?
The easiest place is in your web browser’s URL when you are viewing your project’s dashboard. It will be the string of characters right after .../project/.
Why does the CLI need the supabase project-ref?
The CLI needs the project reference to know which remote Supabase project to connect to. Without it, the CLI has no idea which database to modify, which functions to deploy, or which secrets to manage.
Do I always need to use the --project-ref flag?
No. You can run supabase link --project-ref <your-ref> once to link your local directory to a remote project. After that, the CLI remembers the project for that directory, so you won’t need the flag anymore for most commands. Alternatively, you can set the SUPABASE_PROJECT_ID environment variable.