Supabase Project Ref: Where to Find It, Format & CLI Fixes

Your Supabase project ref is the unique identifier for a Supabase project. You will see it in your project dashboard URL, your Supabase API URL, and CLI commands such as supabase link --project-ref.

It matters because Supabase tools need to know which remote project they should connect to. If the ref is missing, copied incorrectly, or formatted wrong, the CLI can fail with errors like:

• required flag(s) "project-ref" not set
• Invalid project ref format. Must be like 'abcdefghijklmnopqrst'

This guide shows you where to find your Supabase project ref, what a valid project ref looks like, how to use it with the Supabase CLI, how to manage staging and production refs, and how to fix the most common project-ref errors.

If you are connecting Supabase to a frontend built in WeWeb, this also helps make sure your app is talking to the right Supabase backend.

Let’s break down everything you need to know.

Quick Answer: Where is the Supabase Project Ref?

You can find your Supabase project ref in your project dashboard URL.

It looks like this:

https://supabase.com/dashboard/project/<project-ref>

The <project-ref> part is your Supabase project ref.

You can also find it inside your Supabase API URL:

https://<project-ref>.supabase.co

For example, if your API URL is:

https://abcdefghijklmnopqrst.supabase.co

Then your project ref is:

abcdefghijklmnopqrst

Use that value when running CLI commands such as:

supabase link --project-ref abcdefghijklmnopqrst

What is a Supabase Project Ref?

A Supabase project ref is the unique identifier assigned to each Supabase project.

You may also see it called:

• Supabase project ref
• Project reference
• Project ID
• Project ref

In most practical contexts, these refer to the same value: the unique string that identifies your Supabase project.

You will use it when:

• Linking a local project with the Supabase CLI.
• Running CLI commands against a remote Supabase project.
• Configuring CI/CD workflows.
• Identifying staging and production Supabase projects.
• Reading your Supabase API URL.
• Connecting a frontend or app builder to the correct backend project.

Example:

https://abcdefghijklmnopqrst.supabase.co

In this URL, the project ref is:

abcdefghijklmnopqrst

Supabase Project Ref Format

A valid Supabase project ref is:

• Exactly 20 characters long.
• Lowercase only.
• Usually made of lowercase letters, and may include numbers.
• Not a full URL.
• Not your database password.
• Not your anon key.
• Not your service role key.
• Not your project name.

Valid example:

abcdefghijklmnopqrst

Invalid examples:

https://abcdefghijklmnopqrst.supabase.co
This is the full API URL, not just the project ref.

ABCDEFGHIJKLMNOPQRST
Project refs are lowercase.

abc123
Too short.

my-supabase-project
This is a project name, not a project ref.

If the value does not match the expected format, the CLI may return:

Invalid project ref format. Must be like 'abcdefghijklmnopqrst'.

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_TOKEN
• SUPABASE_DB_PASSWORD
• SUPABASE_PROJECT_ID

Configuring Production and Staging Project Refs

To manage your staging and production environments effectively, you should use distinct project references for each.

1. Create Two Projects: Create one Supabase project for staging and another for production. Each will have its own unique supabase project-ref.
2. Store IDs Securely: Store these two project refs as secrets in your deployment environment. A common naming convention is STAGING_PROJECT_ID and PRODUCTION_PROJECT_ID.
3. Use in Workflows: In your deployment scripts, you can load the appropriate ID into the SUPABASE_PROJECT_ID variable depending on the target environment. For example, a deployment to your main branch would use PRODUCTION_PROJECT_ID, while a deployment to a develop branch would use STAGING_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 set
• Error: 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.

1. Add the --project-ref Flag: The quickest fix is to simply add the flag to the command you just ran. For example: supabase link --project-ref yourprojectrefhere.
2. 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.
3. Check Your Environment Variables: If you’re in a CI/CD environment, ensure the SUPABASE_PROJECT_ID environment variable is correctly set and available to the script.
4. 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.

Using Supabase Project Refs with WeWeb

If you are building a Supabase-powered app in WeWeb, the project ref helps you confirm that your frontend is connected to the correct Supabase backend.

You may see the project ref inside your Supabase API URL:

https://abcdefghijklmnopqrst.supabase.co

In this example, the project ref is:

abcdefghijklmnopqrst

This matters when you are managing multiple environments. For example, your WeWeb staging app should point to your staging Supabase project, while your production WeWeb app should point to your production Supabase project.

A clean setup usually looks like this:

• WeWeb staging → Supabase staging project
• WeWeb production → Supabase production project

That separation helps you test database changes, authentication, API calls, and edge functions before they affect real users.

With WeWeb, builders can create the app layer on top of Supabase: dashboards, portals, internal tools, SaaS apps, admin panels, and authenticated user experiences connected to Supabase data.

Supabase Project Ref Checklist

Before running CLI commands or connecting your app, check that:

• You copied only the project ref, not the full URL.
• The ref is exactly 20 characters.
• The ref is lowercase.
• There are no spaces, quotes, or trailing characters.
• You are using the right ref for the right environment.
• Your local CLI project is linked to the intended Supabase project.
• Your CI/CD secrets use the right SUPABASE_PROJECT_ID.
• Your WeWeb staging app points to Supabase staging.
• Your WeWeb production app points to Supabase production.
• Secrets such as service role keys and database passwords are stored separately and securely.

Frequently Asked Questions

What is a Supabase project ref?

A Supabase project ref is the unique identifier for a Supabase project. It appears in your dashboard URL and API URL, and it is used by the Supabase CLI to target the correct remote project.

Is Supabase project ref the same as project ID?

In most practical contexts, yes. Supabase project ref, project reference, and project ID usually refer to the same unique project identifier.

Where do I find my Supabase project ref?

Open your Supabase project dashboard and look at the URL:

https://supabase.com/dashboard/project/<project-ref>

The value after /project/ is your project ref.

You can also find it in your Supabase API URL:

https://<project-ref>.supabase.co

Is the Supabase project ref a secret?

No. The project ref is an identifier, not a secret. However, keys, database passwords, access tokens, and service role keys should be treated as secrets and stored securely.

Why does the Supabase CLI need a project ref?

The CLI needs the project ref to know which remote Supabase project to link to, pull from, push to, or deploy functions against.

Do I need --project-ref for every CLI command?

No. If you run supabase link --project-ref <project-ref> once in your local directory, the CLI remembers the remote project context for that directory. In CI/CD, use SUPABASE_PROJECT_ID.

Why am I getting “Invalid project ref format”?

You probably pasted the wrong value. Use only the project ref, not the full API URL, dashboard URL, project name, anon key, service role key, or database password.

Can I change my Supabase project ref?

No. The project ref is assigned when the project is created and cannot be changed. To get a different project ref, you would need to create a new Supabase project.

Should staging and production use different Supabase project refs?

Yes. For serious apps, staging and production should use separate Supabase projects, which means separate project refs. This reduces the risk of testing against production data or deploying changes to the wrong environment.

How does this matter when using Supabase with WeWeb?

If your WeWeb app connects to Supabase, the project ref helps you verify which Supabase backend your app is using. Make sure WeWeb staging connects to Supabase staging and WeWeb production connects to Supabase production.