Supabase CLI

Why You Need This

You're working on Project 2. You add a new column to the inquiries table — let's say you need to capture the client's preferred_callback_time. You add the column in the Supabase dashboard: open browser, navigate to the project, go to the Table Editor, find the table, add column, save.

Done. Works locally — your test data has the new column.

Six weeks later, you create a staging environment. Or a teammate joins. Or you need to set up the project fresh on a new machine. The database there doesn't have preferred_callback_time. Your app crashes on that screen. You spend time figuring out what's different. You add the column manually again. You forget one table's RLS policy while you're at it.

The CLI solves this. Instead of manually clicking around the dashboard, you write a migration file — a SQL file that describes the change. The CLI applies that file to any environment, any time, consistently. Every database change becomes a reproducible instruction.

This is the same principle as Git for code: your database changes become a history of files, not a series of manual clicks you have to remember.

Excel analogy: Imagine writing your monthly reporting process as a step-by-step macro instead of doing it by clicking menus. Anyone who runs the macro gets the same result. The CLI lets you write your database changes as a "macro" that any environment can run.

Installation

The Supabase CLI is a Node.js tool. Install it globally so it's available in any project.

Run npm install -g supabase in your terminal. The installation takes 30–60 seconds.

Verify the installation worked by running supabase --version. You should see a version number like 1.200.3. If you see command not found, close your terminal, reopen it, and try again.

Logging In

The CLI needs to know who you are. Run supabase login in your terminal.

This opens your browser and takes you to the Supabase login page. After you authenticate, it saves a token to your computer so every subsequent CLI command knows your identity.

What actually happens: The CLI stores an access token in your system's credential store. You don't see it, and you don't need to manage it — just log in once per machine.

If you ever need to use a specific token (for example, in an automated script), you can pass it directly:

This is the access token you generated in the API Keys page and saved to VaultMate.

Finding Your Project Reference ID

Nearly every CLI command that operates on a specific project requires your project reference ID — a 20-character string that uniquely identifies your project.

Where to find it:

1. Supabase dashboard → your project
2. Left sidebar → Settings (gear icon)
3. Click General
4. Look for Reference ID — it looks like abcdefghijklmnopqrst

You can also find it in your Project URL: if your URL is https://abcdefghijklmnop.supabase.co, then abcdefghijklmnop is your project ref.

Pro tip: Save this in your project's CLAUDE.md file. You'll type it frequently, and having it one copy-paste away saves time every session:

You can also list all your projects to find the ref by running supabase projects list. The output shows your project names alongside their reference IDs.

The Five Commands You'll Use on Every Project

Command 1: Generate TypeScript Types

This is the command you will run most often. It reads your current database schema — every table, every column, every data type — and generates a TypeScript file that describes it all.

Run: supabase gen types typescript --project-id YOUR_PROJECT_REF > src/lib/database.types.ts

Replace YOUR_PROJECT_REF with your actual project reference ID from supabase projects list.

When to run it: Every time you change your database schema. Add a table → run it. Add a column → run it. Rename a column → run it. Make it a habit: schema change, then immediately regenerate.

The generated file is long and looks complex — you never edit it manually. It is machine-generated and machine-read. You just use it.

Command 2: List Your Projects

Shows all Supabase projects under your account. Useful for finding project reference IDs when you have multiple projects.

Command 3: Pull Schema (Sync Cloud to Local)

Downloads your remote database schema as migration files into a local supabase/migrations/ folder. Use this when:

• You've been making changes in the Supabase dashboard and want to capture them as migration files
• You're setting up a project from scratch and want to start tracking schema changes

Output:

Command 4: Push Migrations (Apply Local Changes to Cloud)

Applies any new migration files in your local supabase/migrations/ folder to the remote database. Use this when:

• You've written a new migration file (a SQL change) and want to apply it to production
• You're setting up the project on a new environment and need to bring the database up to date

Output:

Command 5: Deploy Edge Functions

Deploys a single edge function from your local supabase/functions/ folder to Supabase. Replace function-name with the name of the function folder.

To deploy all functions at once:

Output:

Migrations — The Concept Behind Commands 3 and 4

A migration file is a SQL file that describes one change to your database. Each file has a timestamp in its name so they apply in the correct order.

You create migration files in two ways:

Option A — Write them manually: Create a new .sql file in supabase/migrations/ with a timestamp prefix and write the SQL yourself. Use supabase db push to apply it.

Option B — Use the CLI to create the file: This creates an empty migration file with the correct timestamp. Then you write the SQL inside it.

Claude Code can write migration files for you. When you ask "add a preferred_callback_time column to the inquiries table," Claude will write the SQL and place it in the correct folder. You review it, then push.

Quick Reference: CLI Commands

The Typical Workflow for a Schema Change

This is the sequence you'll follow every time you change your database: