Supabase

CLI Reference | Supabase Docs

/docs/reference/cli/supabase-vanity-subdomains

docs

Words: 8,548
Reading time: 39 min
Published: 2026-08-27
Last crawled: 2026-08-27
Language: EN

surface: e-reader

Notes Letter System 7 Laptop Word processor Terminal Vending machine Manuscript Receipt Index cards Blueprint Broadsheet E-reader Spiral notebook Slide deck File window Compare all sixteen →

CLI Reference | Supabase Docs

Supabase · 2026-08-27

Flags

-p, --password <string>

Optional

Password to your remote Postgres database.

Initialize configurations for Supabase local development.

A supabase/config.toml file is created in your current working directory. This configuration is specific to each local project.

You may override the directory path by specifying the SUPABASE_WORKDIR environment variable or --workdir flag.

In addition to config.toml, the supabase directory may also contain other Supabase objects, such as migrations, functions, tests, etc.

Flags

--force

Optional

Overwrite existing supabase/config.toml.
-i, --interactive

Optional

Enables interactive mode to configure IDE settings.
--use-orioledb

Optional

Use OrioleDB storage engine for Postgres.

Connect the Supabase CLI to your Supabase account by logging in with your personal access token.

Your access token is stored securely in native credentials storage. If native credentials storage is unavailable, it will be written to a plain text file at ~/.supabase/access-token.

If this behavior is not desired, such as in a CI environment, you may skip login by specifying the SUPABASE_ACCESS_TOKEN environment variable in other commands.

The Supabase CLI uses the stored token to access Management APIs for projects, functions, secrets, etc.

Flags

--name <string>

Optional

Name that will be used to store token in your settings
--no-browser

Optional

Do not open browser automatically
--token <string>

Optional

Use provided token instead of automatic login flow

Link your local development project to a hosted Supabase project.

PostgREST configurations are fetched from the Supabase platform and validated against your local configuration file.

Optionally, database settings can be validated if you provide a password. Your database password is saved in native credentials storage if available.

If you do not want to be prompted for the database password, such as in a CI environment, you may specify it explicitly via the SUPABASE_DB_PASSWORD environment variable.

Some commands like db dump, db push, and db pull require your project to be linked first.

Flags

-p, --password <string>

Optional

Password to your remote Postgres database.
--project-ref <string>

Optional

Project ref of the Supabase project.
--skip-pooler

Optional

Use direct connection instead of pooler.

Starts the Supabase local development stack.

Requires supabase/config.toml to be created in your current working directory by running supabase init.

All service containers are started by default. You can exclude those not needed by passing in -x flag. To exclude multiple containers, either pass in a comma separated string, such as -x gotrue,imgproxy, or specify -x flag multiple times.

It is recommended to have at least 7GB of RAM to start all services.

Health checks are automatically added to verify the started containers. Use --ignore-health-check flag to ignore these errors.

If the CLI is running inside a dev container with the Docker socket bind-mounted, set the SUPABASE_SERVICES_HOSTNAME environment variable to the hostname reachable from inside that container, such as host.docker.internal.

Flags

-x, --exclude <strings>

Optional

Names of containers to not start. [gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor]
--ignore-health-check

Optional

Ignore unhealthy services and exit 0

Stops the Supabase local development stack.

Requires supabase/config.toml to be created in your current working directory by running supabase init.

All Docker resources are maintained across restarts. Use --no-backup flag to reset your local development data between restarts.

Use the --all flag to stop all local Supabase projects instances on the machine. Use with caution with --no-backup as it will delete all supabase local projects data.

Flags

--all

Optional

Stop all local Supabase instances from all projects across the machine.
--no-backup

Optional

Deletes all data volumes after stopping.
--project-id <string>

Optional

Local project ID to stop.

Shows status of the Supabase local development stack.

Requires the local development stack to be started by running supabase start or supabase db start.

You can export the connection parameters for initializing supabase-js locally by specifying the -o env flag. Supported parameters include JWT_SECRET, ANON_KEY, and SERVICE_ROLE_KEY.

Flags

--override-name <strings>

Optional

Override specific variable names.

Executes pgTAP tests against the local database.

Requires the local development stack to be started by running supabase start.

Runs pg_prove in a container with unit test files volume mounted from supabase/tests directory. The test file can be suffixed by either .sql or .pg extension.

Since each test is wrapped in its own transaction, it will be individually rolled back regardless of success or failure.

Flags

--db-url <string>

Optional

Tests the database specified by the connection string (must be percent-encoded).
--linked

Optional

Runs pgTAP tests on the linked project.
--local

Optional

Runs pgTAP tests on the local database.

Flags

-t, --template <[ pgtap ]>

Optional

Template framework to generate.

Automatically generates type definitions based on your Postgres database schema.

This command connects to your database (local or remote) and generates typed definitions that match your database tables, views, and stored procedures. By default, it generates TypeScript definitions, but also supports Go and Swift.

Generated types give you type safety and autocompletion when working with your database in code, helping prevent runtime errors and improving developer experience.

The types respect relationships, constraints, and custom types defined in your database schema.

Subcommands

Securely generate a private JWT signing key for use in the CLI or to import in the dashboard.

Supported algorithms: ES256 - ECDSA with P-256 curve and SHA-256 (recommended) RS256 - RSA with SHA-256

Flags

--algorithm <[ RS256 | ES256 ]>

Optional

Algorithm for signing key generation.
--append

Optional

Append new key to existing keys file instead of overwriting.

Flags

--db-url <string>

Optional

Generate types from a database url.
--lang <[ typescript | go | swift | python ]>

Optional

Output language of the generated types.
--linked

Optional

Generate types from the linked project.
--local

Optional

Generate types from the local dev database.
--postgrest-v9-compat

Optional

Generate types compatible with PostgREST v9 and below.
--project-id <string>

Optional

Generate types from a project ID.
--query-timeout <duration>

Optional

Maximum timeout allowed for the database query.
-s, --schema <strings>

Optional

Comma separated list of schema to include.
--swift-access-control <[ internal | public ]>

Optional

Access control for Swift generated types.

Subcommands

Pulls schema changes from a remote database. A new migration file will be created under supabase/migrations directory.

Requires your local project to be linked to a remote database by running supabase link. For self-hosted databases, you can pass in the connection parameters using --db-url flag.

Note this command requires Docker Desktop (or a running Docker daemon), as it starts a local Postgres container to diff your remote schema.

Optionally, a new row can be inserted into the migration history table to reflect the current state of the remote database.

If no entries exist in the migration history table, pg_dump will be used to capture all contents of the remote schemas you have created. Otherwise, this command will only diff schema changes against the remote database, similar to running db diff --linked.

Pass --diff-engine pg-delta to keep the migration-file db pull workflow while using pg-delta for the shadow diff step. Pass --use-pg-delta to switch to the declarative pg-delta export workflow instead.

Flags

--db-url <string>

Optional

Pulls from the database specified by the connection string (must be percent-encoded).
--diff-engine <[ migra | pg-delta ]>

Optional

Diff engine to use for migration-style db pull.
--linked

Optional

Pulls from the linked project.
--local

Optional

Pulls from the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.
-s, --schema <strings>

Optional

Comma separated list of schema to include.
--use-pg-delta

Optional

Use pg-delta to pull declarative schema.

Pushes all local migrations to a remote database.

Requires your local project to be linked to a remote database by running supabase link. For self-hosted databases, you can pass in the connection parameters using --db-url flag.

The first time this command is run, a migration history table will be created under supabase_migrations.schema_migrations. After successfully applying a migration, a new row will be inserted into the migration history table with timestamp as its unique id. Subsequent pushes will skip migrations that have already been applied.

If you need to mutate the migration history table, such as deleting existing entries or inserting new entries without actually running the migration, use the migration repair command.

Use the --dry-run flag to view the list of changes before applying.

Flags

--db-url <string>

Optional

Pushes to the database specified by the connection string (must be percent-encoded).
--dry-run

Optional

Print the migrations that would be applied, but don't actually apply them.
--include-all

Optional

Include all migrations not found on remote history table.
--include-roles

Optional

Include custom roles from supabase/roles.sql.
--include-seed

Optional

Include seed data from your config.
--linked

Optional

Pushes to the linked project.
--local

Optional

Pushes to the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.

Resets the local database to a clean state.

Requires the local development stack to be started by running supabase start.

Recreates the local Postgres container and applies all local migrations found in supabase/migrations directory. If test data is defined in supabase/seed.sql, it will be seeded after the migrations are run. Any other data or schema changes made during local development will be discarded.

When running db reset with --linked or --db-url flag, a SQL script is executed to identify and drop all user created entities in the remote database. Since Postgres roles are cluster level entities, any custom roles created through the dashboard or supabase/roles.sql will not be deleted by remote reset.

Flags

--db-url <string>

Optional

Resets the database specified by the connection string (must be percent-encoded).
--last <uint>

Optional

Reset up to the last n migration versions.
--linked

Optional

Resets the linked project with local migrations.
--local

Optional

Resets the local database with local migrations.
--no-seed

Optional

Skip running the seed script after reset.
--version <string>

Optional

Reset up to the specified version.

Dumps contents from a remote database.

Requires your local project to be linked to a remote database by running supabase link. For self-hosted databases, you can pass in the connection parameters using --db-url flag.

Runs pg_dump in a container with additional flags to exclude Supabase managed schemas. The ignored schemas include auth, storage, and those created by extensions.

The default dump does not contain any data or custom roles. To dump those contents explicitly, specify either the --data-only and --role-only flag.

Note on Privilege Migration

When restoring to a new project, tables inherit ALL privileges from default privileges in the target database. To preserve specific privileges from your dump, revoke defaults before restoring:

-- Run BEFORE restoring your schema
ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM anon, authenticated;

Flags

--data-only

Optional

Dumps only data records.
--db-url <string>

Optional

Dumps from the database specified by the connection string (must be percent-encoded).
--dry-run

Optional

Prints the pg_dump script that would be executed.
-x, --exclude <strings>

Optional

List of schema.tables to exclude from data-only dump.
-f, --file <string>

Optional

File path to save the dumped contents.
--keep-comments

Optional

Keeps commented lines from pg_dump output.
--linked

Optional

Dumps from the linked project.
--local

Optional

Dumps from the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.
--role-only

Optional

Dumps only cluster roles.
-s, --schema <strings>

Optional

Comma separated list of schema to include.
--use-copy

Optional

Use copy statements in place of inserts.

Diffs schema changes made to the local or remote database.

Requires the local development stack to be running when diffing against the local database. To diff against a remote or self-hosted database, specify the --linked or --db-url flag respectively.

Runs djrobstep/migra in a container to compare schema differences between the target database and a shadow database. The shadow database is created by applying migrations in local supabase/migrations directory in a separate container. Output is written to stdout by default. For convenience, you can also save the schema diff as a new migration file by passing in -f flag.

By default, all schemas in the target database are diffed. Use the --schema public,extensions flag to restrict diffing to a subset of schemas.

While the diff command is able to capture most schema changes, there are cases where it is known to fail. Currently, this could happen if you schema contains:

Changes to publication
Changes to storage buckets
Views with security_invoker attributes

Flags

--db-url <string>

Optional

Diffs against the database specified by the connection string (must be percent-encoded).
-f, --file <string>

Optional

Saves schema diff to a new migration file.
--from <string>

Optional

Diff from local, linked, migrations, or a Postgres URL.
--linked

Optional

Diffs local migration files against the linked project.
--local

Optional

Diffs local migration files against the local database.
-o, --output <string>

Optional

Write explicit diff output to a file path.
-s, --schema <strings>

Optional

Comma separated list of schema to include.
--to <string>

Optional

Diff to local, linked, migrations, or a Postgres URL.
--use-migra

Optional

Use migra to generate schema diff.
--use-pg-delta

Optional

Use pg-delta to generate schema diff.
--use-pg-schema

Optional

Use pg-schema-diff to generate schema diff.
--use-pgadmin

Optional

Use pgAdmin to generate schema diff.

Lints local database for schema errors.

Requires the local development stack to be running when linting against the local database. To lint against a remote or self-hosted database, specify the --linked or --db-url flag respectively.

Runs plpgsql_check extension in the local Postgres container to check for errors in all schemas. The default lint level is warning and can be raised to error via the --level flag.

To lint against specific schemas only, pass in the --schema flag.

The --fail-on flag can be used to control when the command should exit with a non-zero status code. The possible values are:

none (default): Always exit with a zero status code, regardless of lint results.
warning: Exit with a non-zero status code if any warnings or errors are found.
error: Exit with a non-zero status code only if errors are found.

This flag is particularly useful in CI/CD pipelines where you want to fail the build based on certain lint conditions.

Flags

--db-url <string>

Optional

Lints the database specified by the connection string (must be percent-encoded).
--fail-on <[ none | warning | error ]>

Optional

Error level to exit with non-zero status.
--level <[ warning | error ]>

Optional

Error level to emit.
--linked

Optional

Lints the linked project for schema errors.
--local

Optional

Lints the local database for schema errors.
-s, --schema <strings>

Optional

Comma separated list of schema to include.

Flags

--from-backup <string>

Optional

Path to a logical backup file.

Subcommands

Creates a new migration file locally.

A supabase/migrations directory will be created if it does not already exists in your current workdir. All schema migration files must be created in this directory following the pattern <timestamp>_<name>.sql.

Outputs from other commands like db diff may be piped to migration new <name> via stdin.

Lists migration history in both local and remote databases.

Requires your local project to be linked to a remote database by running supabase link. For self-hosted databases, you can pass in the connection parameters using --db-url flag.

Note that URL strings must be escaped according to RFC 3986.

Local migrations are stored in supabase/migrations directory while remote migrations are tracked in supabase_migrations.schema_migrations table. Only the timestamps are compared to identify any differences.

In case of discrepancies between the local and remote migration history, you can resolve them using the migration repair command.

Flags

--db-url <string>

Optional

Lists migrations of the database specified by the connection string (must be percent-encoded).
--linked

Optional

Lists migrations applied to the linked project.
--local

Optional

Lists migrations applied to the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.

Flags

--db-url <string>

Optional

Fetches migrations from the database specified by the connection string (must be percent-encoded).
--linked

Optional

Fetches migration history from the linked project.
--local

Optional

Fetches migration history from the local database.

Repairs the remote migration history table.

Requires your local project to be linked to a remote database by running supabase link.

If your local and remote migration history goes out of sync, you can repair the remote history by marking specific migrations as --status applied or --status reverted. Marking as reverted will delete an existing record from the migration history table while marking as applied will insert a new record.

For example, your migration history may look like the table below, with missing entries in either local or remote.

$ supabase migration list
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
                   │ 20230103054303 │ 2023-01-03 05:43:03
   20230103054315  │                │ 2023-01-03 05:43:15

To reset your migration history to a clean state, first delete your local migration file.

$ rm supabase/migrations/20230103054315_remote_commit.sql

$ supabase migration list
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
                   │ 20230103054303 │ 2023-01-03 05:43:03

Then mark the remote migration 20230103054303 as reverted.

$ supabase migration repair 20230103054303 --status reverted
Connecting to remote database...
Repaired migration history: [20220810154537] => reverted
Finished supabase migration repair.

$ supabase migration list
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────

Now you can run db pull again to dump the remote schema as a local migration file.

$ supabase db pull
Connecting to remote database...
Schema written to supabase/migrations/20240414044403_remote_schema.sql
Update remote migration history table? [Y/n]
Repaired migration history: [20240414044403] => applied
Finished supabase db pull.

$ supabase migration list
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
    20240414044403 │ 20240414044403 │ 2024-04-14 04:44:03

Flags

--db-url <string>

Optional

Repairs migrations of the database specified by the connection string (must be percent-encoded).
--linked

Optional

Repairs the migration history of the linked project.
--local

Optional

Repairs the migration history of the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.
--status <[ applied | reverted ]>

Required

Version status to update.

Squashes local schema migrations to a single migration file.

The squashed migration is equivalent to a schema only dump of the local database after applying existing migration files. This is especially useful when you want to remove repeated modifications of the same schema from your migration history.

However, one limitation is that data manipulation statements, such as insert, update, or delete, are omitted from the squashed migration. You will have to add them back manually in a new migration file. This includes cron jobs, storage buckets, and any encrypted secrets in vault.

By default, the latest <timestamp>_<name>.sql file will be updated to contain the squashed migration. You can override the target version using the --version <timestamp> flag.

If your supabase/migrations directory is empty, running supabase squash will do nothing.

Flags

--db-url <string>

Optional

Squashes migrations of the database specified by the connection string (must be percent-encoded).
--linked

Optional

Squashes the migration history of the linked project.
--local

Optional

Squashes the migration history of the local database.
-p, --password <string>

Optional

Password to your remote Postgres database.
--version <string>

Optional

Squash up to the specified version.

Flags

--db-url <string>

Optional

Applies migrations to the database specified by the connection string (must be percent-encoded).
--include-all

Optional

Include all migrations not found on remote history table.
--linked

Optional

Applies pending migrations to the linked project.
--local

Optional

Applies pending migrations to the local database.

Flags

--db-url <string>

Optional

Resets applied migrations on the database specified by the connection string (must be percent-encoded).
--last <uint>

Optional

Reset up to the last n migration versions.
--linked

Optional

Resets applied migrations on the linked project.
--local

Optional

Resets applied migrations on the local database.

Flags

--linked

Optional

Seeds the linked project.
--local

Optional

Seeds the local database.

Subcommands

This command displays an estimation of table "bloat" - Due to Postgres' MVCC when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the autovaccum process will asynchronously clean the dead tuples. Sometimes the autovaccum is unable to work fast enough to reduce or prevent tables from becoming bloated. High bloat can slow down queries, cause excessive IOPS and waste space in your database.

Tables with a high bloat ratio should be investigated to see if there are vacuuming is not quick enough or there are other issues.

    TYPE  │ SCHEMA NAME │        OBJECT NAME         │ BLOAT │ WASTE
  ────────┼─────────────┼────────────────────────────┼───────┼─────────────
    table │ public      │ very_bloated_table         │  41.0 │ 700 MB
    table │ public      │ my_table                   │   4.0 │ 76 MB
    table │ public      │ happy_table                │   1.0 │ 1472 kB
    index │ public      │ happy_table::my_nice_index │   0.7 │ 880 kB

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command shows you statements that are currently holding locks and blocking, as well as the statement that is being blocked. This can be used in conjunction with inspect db locks to determine which statements need to be terminated in order to resolve lock contention.

    BLOCKED PID │ BLOCKING STATEMENT           │ BLOCKING DURATION │ BLOCKING PID │ BLOCKED STATEMENT                                                                      │ BLOCKED DURATION
  ──────────────┼──────────────────────────────┼───────────────────┼──────────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────
    253         │ select count(*) from mytable │ 00:00:03.838314   │        13495 │ UPDATE "mytable" SET "updated_at" = '2023─08─03 14:07:04.746688' WHERE "id" = 83719341 │ 00:00:03.821826

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command is much like the supabase inspect db outliers command, but ordered by the number of times a statement has been called.

You can use this information to see which queries are called most often, which can potentially be good candidates for optimisation.


                        QUERY                      │ TOTAL EXECUTION TIME │ PROPORTION OF TOTAL EXEC TIME │ NUMBER CALLS │  SYNC IO TIME
  ─────────────────────────────────────────────────┼──────────────────────┼───────────────────────────────┼──────────────┼──────────────────
    SELECT * FROM users WHERE id = $1              │ 14:50:11.828939      │ 89.8%                         │  183,389,757 │ 00:00:00.002018
    SELECT * FROM user_events                      │ 01:20:23.466633      │ 1.4%                          │       78,325 │ 00:00:00
    INSERT INTO users (email, name) VALUES ($1, $2)│ 00:40:11.616882      │ 0.8%                          │       54,003 │ 00:00:00.000322

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command displays queries that have taken out an exclusive lock on a relation. Exclusive locks typically prevent other operations on that relation from taking place, and can be a cause of "hung" queries that are waiting for a lock to be granted.

If you see a query that is hanging for a very long time or causing blocking issues you may consider killing the query by connecting to the database and running SELECT pg_cancel_backend(PID); to cancel the query. If the query still does not stop you can force a hard stop by running SELECT pg_terminate_backend(PID);

     PID   │ RELNAME │ TRANSACTION ID │ GRANTED │                  QUERY                  │   AGE
  ─────────┼─────────┼────────────────┼─────────┼─────────────────────────────────────────┼───────────
    328112 │ null    │              0 │ t       │ SELECT * FROM logs;                     │ 00:04:20

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command displays currently running queries, that have been running for longer than 5 minutes, descending by duration. Very long running queries can be a source of multiple issues, such as preventing DDL statements completing or vacuum being unable to update relfrozenxid.

  PID  │     DURATION    │                                         QUERY
───────┼─────────────────┼───────────────────────────────────────────────────────────────────────────────────────
 19578 | 02:29:11.200129 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1450645 LIMIT 1
 19465 | 02:26:05.542653 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1889881 LIMIT 1
 19632 | 02:24:46.962818 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1581884 LIMIT 1

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command displays statements, obtained from pg_stat_statements, ordered by the amount of time to execute in aggregate. This includes the statement itself, the total execution time for that statement, the proportion of total execution time for all statements that statement has taken up, the number of times that statement has been called, and the amount of time that statement spent on synchronous I/O (reading/writing from the file system).

Typically, an efficient query will have an appropriate ratio of calls to total execution time, with as little time spent on I/O as possible. Queries that have a high total execution time but low call count should be investigated to improve their performance. Queries that have a high proportion of execution time being spent on synchronous I/O should also be investigated.


                 QUERY                   │ EXECUTION TIME   │ PROPORTION OF EXEC TIME │ NUMBER CALLS │ SYNC IO TIME
─────────────────────────────────────────┼──────────────────┼─────────────────────────┼──────────────┼───────────────
 SELECT * FROM archivable_usage_events.. │ 154:39:26.431466 │ 72.2%                   │ 34,211,877   │ 00:00:00
 COPY public.archivable_usage_events (.. │ 50:38:33.198418  │ 23.6%                   │ 13           │ 13:34:21.00108
 COPY public.usage_events (id, reporte.. │ 02:32:16.335233  │ 1.2%                    │ 13           │ 00:34:19.784318
 INSERT INTO usage_events (id, retaine.. │ 01:42:59.436532  │ 0.8%                    │ 12,328,187   │ 00:00:00
 SELECT * FROM usage_events WHERE (alp.. │ 01:18:10.754354  │ 0.6%                    │ 102,114,301  │ 00:00:00

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command shows information about logical replication slots that are setup on the database. It shows if the slot is active, the state of the WAL sender process ('startup', 'catchup', 'streaming', 'backup', 'stopping') the replication client address and the replication lag in GB.

This command is useful to check that the amount of replication lag is as low as possible, replication lag can occur due to network latency issues, slow disk I/O, long running transactions or lack of ability for the subscriber to consume WAL fast enough.

                       NAME                    │ ACTIVE │ STATE   │ REPLICATION CLIENT ADDRESS │ REPLICATION LAG GB
  ─────────────────────────────────────────────┼────────┼─────────┼────────────────────────────┼─────────────────────
    supabase_realtime_replication_slot         │ t      │ N/A     │ N/A                        │                  0
    datastream                                 │ t      │ catchup │ 24.201.24.106              │                 45

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This command analyzes table I/O patterns to show read/write activity ratios based on block-level operations. It combines data from PostgreSQL's pg_stat_user_tables (for tuple operations) and pg_statio_user_tables (for block I/O) to categorize each table's workload profile.

The command classifies tables into categories:

Read-Heavy - Read operations are more than 5x write operations (e.g., 1:10, 1:50)
Write-Heavy - Write operations are more than 20% of read operations (e.g., 1:2, 1:4, 2:1, 10:1)
Balanced - Mixed workload where writes are between 20% and 500% of reads
Read-Only - Only read operations detected
Write-Only - Only write operations detected

SCHEMA │ TABLE        │ BLOCKS READ │ WRITE TUPLES │ BLOCKS WRITE │ ACTIVITY RATIO
───────┼──────────────┼─────────────┼──────────────┼──────────────┼────────────────────
public │ user_events  │     450,234 │     9,004,680│       23,450 │ 20:1 (Write-Heavy)
public │ users        │      89,203 │        12,451│        1,203 │ 7.2:1 (Read-Heavy)
public │ sessions     │      15,402 │        14,823│        2,341 │ ≈1:1 (Balanced)
public │ cache_data   │     123,456 │             0│            0 │ Read-Only
auth   │ audit_logs   │           0 │        98,234│       12,341 │ Write-Only

Note: This command only displays tables that have had both read and write activity. Tables with no I/O operations are not shown. The classification ratio threshold (default: 5:1) determines when a table is considered "heavy" in one direction versus balanced.

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

This shows you stats about the vacuum activities for each table. Due to Postgres' MVCC when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the autovaccum process will aysnchronously clean the dead tuples.

The command lists when the last vacuum and last auto vacuum took place, the row count on the table as well as the count of dead rows and whether autovacuum is expected to run or not. If the number of dead rows is much higher than the row count, or if an autovacuum is expected but has not been performed for some time, this can indicate that autovacuum is not able to keep up and that your vacuum settings need to be tweaked or that you require more compute or disk IOPS to allow autovaccum to complete.

        SCHEMA        │              TABLE               │ LAST VACUUM │ LAST AUTO VACUUM │      ROW COUNT       │ DEAD ROW COUNT │ EXPECT AUTOVACUUM?
──────────────────────┼──────────────────────────────────┼─────────────┼──────────────────┼──────────────────────┼────────────────┼─────────────────────
 auth                 │ users                            │             │ 2023-06-26 12:34 │               18,030 │              0 │ no
 public               │ profiles                         │             │ 2023-06-26 23:45 │               13,420 │             28 │ no
 public               │ logs                             │             │ 2023-06-26 01:23 │            1,313,033 │      3,318,228 │ yes
 storage              │ objects                          │             │                  │             No stats │              0 │ no
 storage              │ buckets                          │             │                  │             No stats │              0 │ no
 supabase_migrations  │ schema_migrations                │             │                  │             No stats │              0 │ no

Flags

--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Flags

--output-dir <string>

Optional

Path to save CSV files in
--db-url <string>

Optional

Inspect the database specified by the connection string (must be percent-encoded).
--linked

Optional

Inspect the linked project.
--local

Optional

Inspect the local database.

Create an organization for the logged-in user.

List all organizations the logged-in user belongs.

Provides tools for creating and managing your Supabase projects.

This command group allows you to list all projects in your organizations, create new projects, delete existing projects, and retrieve API keys. These operations help you manage your Supabase infrastructure programmatically without using the dashboard.

Project management via CLI is especially useful for automation scripts and when you need to provision environments in a repeatable way.

Subcommands

Flags

--db-password <string>

Optional

Database password of the project.
--org-id <string>

Optional

Organization ID to create the project in.
--region <string>

Optional

Select a region close to you for the best performance.
--size <string>

Optional

Select a desired instance size for your project.

List all Supabase projects the logged-in user can access.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Updates the configurations of a linked Supabase project with the local supabase/config.toml file.

This command allows you to manage project configuration as code by defining settings locally and then pushing them to your remote project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Subcommands

Create a preview branch for the linked project.

Flags

--notify-url <string>

Optional

URL to notify when branch is active healthy.
--persistent

Optional

Whether to create a persistent branch.
--region <string>

Optional

Select a region to deploy the branch database.
--size <string>

Optional

Select a desired instance size for the branch database.
--with-data

Optional

Whether to clone production data to the branch database.
--project-ref <string>

Optional

Project ref of the Supabase project.

List all preview branches of the linked project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Retrieve details of the specified preview branch.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Update a preview branch by its name or ID.

Flags

--git-branch <string>

Optional

Change the associated git branch.
--name <string>

Optional

Rename the preview branch.
--notify-url <string>

Optional

URL to notify when branch is active healthy.
--persistent

Optional

Switch between ephemeral and persistent branch.
--status <string>

Optional

Override the current branch status.
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Delete a preview branch by its name or ID.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Creates a new Edge Function with boilerplate code in the supabase/functions directory.

This command generates a starter TypeScript file with the necessary Deno imports and a basic function structure. The function is created as a new directory with the name you specify, containing an index.ts file with the function code.

After creating the function, you can edit it locally and then use supabase functions serve to test it before deploying with supabase functions deploy.

Flags

--auth <[ none | apikey | user ]>

Optional

use a specific auth mode

List all Functions in the linked Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Download the source code for a Function from the linked Supabase project. If no function name is provided, downloads all functions.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.
--use-api

Optional

Unbundle functions server-side without using Docker.

Serve all Functions locally.

supabase functions serve command includes additional flags to assist developers in debugging Edge Functions via the v8 inspector protocol, allowing for debugging via Chrome DevTools, VS Code, and IntelliJ IDEA for example. Refer to the docs guide for setup instructions.

--inspect
- Alias of --inspect-mode brk.
--inspect-mode [ run | brk | wait ]
- Activates the inspector capability.
- run mode simply allows a connection without additional behavior. It is not ideal for short scripts, but it can be useful for long-running scripts where you might occasionally want to set breakpoints.
- brk mode same as run mode, but additionally sets a breakpoint at the first line to pause script execution before any code runs.
- wait mode similar to brk mode, but instead of setting a breakpoint at the first line, it pauses script execution until an inspector session is connected.
--inspect-main
- Can only be used when one of the above two flags is enabled.
- By default, creating an inspector session for the main worker is not allowed, but this flag allows it.
- Other behaviors follow the inspect-mode flag mentioned above.

Additionally, the following properties can be customized via supabase/config.toml under edge_runtime section.

inspector_port
- The port used to listen to the Inspector session, defaults to 8083.
policy
- A value that indicates how the edge-runtime should forward incoming HTTP requests to the worker.
- per_worker allows multiple HTTP requests to be forwarded to a worker that has already been created.
- oneshot will force the worker to process a single HTTP request and then exit. (Debugging purpose, This is especially useful if you want to reflect changes you've made immediately.)

Flags

--env-file <string>

Optional

Path to an env file to be populated to the Function environment.
--import-map <string>

Optional

Path to import map file.
--inspect

Optional

Alias of --inspect-mode brk.
--inspect-main

Optional

Allow inspecting the main worker.
--inspect-mode <[ run | brk | wait ]>

Optional

Activate inspector capability for debugging.
--no-verify-jwt

Optional

Disable JWT verification for the Function.

Deploy a Function to the linked Supabase project.

Flags

--import-map <string>

Optional

Path to import map file.
-j, --jobs <uint>

Optional

Maximum number of parallel jobs.
--no-verify-jwt

Optional

Disable JWT verification for the Function.
--project-ref <string>

Optional

Project ref of the Supabase project.
--prune

Optional

Delete Functions that exist in Supabase project but not locally.
--use-api

Optional

Bundle functions server-side without using Docker.

Delete a Function from the linked Supabase project. This does NOT remove the Function locally.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Provides tools for managing environment variables and secrets for your Supabase project.

This command group allows you to set, unset, and list secrets that are securely stored and made available to Edge Functions as environment variables.

Secrets management through the CLI is useful for:

Setting environment-specific configuration
Managing sensitive credentials securely

Secrets can be set individually or loaded from .env files for convenience.

Subcommands

Set a secret(s) to the linked Supabase project.

Flags

--env-file <string>

Optional

Read secrets from a .env file.
--project-ref <string>

Optional

Project ref of the Supabase project.

List all secrets in the linked project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Unset a secret(s) from the linked Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

-r, --recursive

Optional

Recursively list a directory.
--experimental

Required

enable experimental features
--linked

Optional

Connects to Storage API of the linked project.
--local

Optional

Connects to Storage API of the local database.

Flags

--cache-control <string>

Optional

Custom Cache-Control header for HTTP upload.
--content-type <string>

Optional

Custom Content-Type header for HTTP upload.
-j, --jobs <uint>

Optional

Maximum number of parallel jobs.
-r, --recursive

Optional

Recursively copy a directory.
--experimental

Required

enable experimental features
--linked

Optional

Connects to Storage API of the linked project.
--local

Optional

Connects to Storage API of the local database.

Flags

-r, --recursive

Optional

Recursively move a directory.
--experimental

Required

enable experimental features
--linked

Optional

Connects to Storage API of the linked project.
--local

Optional

Connects to Storage API of the local database.

Flags

-r, --recursive

Optional

Recursively remove a directory.
--experimental

Required

enable experimental features
--linked

Optional

Connects to Storage API of the linked project.
--local

Optional

Connects to Storage API of the local database.

Subcommands

Add and configure a new connection to a SSO identity provider to your Supabase project.

Flags

--attribute-mapping-file <string>

Optional

File containing a JSON mapping between SAML attributes to custom JWT claims.
--domains <strings>

Optional

Comma separated list of email domains to associate with the added identity provider.
--metadata-file <string>

Optional

File containing a SAML 2.0 Metadata XML document describing the identity provider.
--metadata-url <string>

Optional

URL pointing to a SAML 2.0 Metadata XML document describing the identity provider.
--name-id-format <string>

Optional

URI reference representing the classification of string-based identifier information.
--skip-url-validation

Optional

Whether local validation of the SAML 2.0 Metadata URL should not be performed.
-t, --type <[ saml ]>

Required

Type of identity provider (according to supported protocol).
--project-ref <string>

Optional

Project ref of the Supabase project.

List all connections to a SSO identity provider to your Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Provides the information about an established connection to an identity provider. You can use --metadata to obtain the raw SAML 2.0 Metadata XML document stored in your project's configuration.

Flags

--metadata

Optional

Show SAML 2.0 XML Metadata only
--project-ref <string>

Optional

Project ref of the Supabase project.

Returns all of the important SSO information necessary for your project to be registered with a SAML 2.0 compatible identity provider.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Update the configuration settings of a already added SSO identity provider.

Flags

--add-domains <strings>

Optional

Add this comma separated list of email domains to the identity provider.
--attribute-mapping-file <string>

Optional

File containing a JSON mapping between SAML attributes to custom JWT claims.
--domains <strings>

Optional

Replace domains with this comma separated list of email domains.
--metadata-file <string>

Optional

File containing a SAML 2.0 Metadata XML document describing the identity provider.
--metadata-url <string>

Optional

URL pointing to a SAML 2.0 Metadata XML document describing the identity provider.
--name-id-format <string>

Optional

URI reference representing the classification of string-based identifier information.
--remove-domains <strings>

Optional

Remove this comma separated list of email domains from the identity provider.
--skip-url-validation

Optional

Whether local validation of the SAML 2.0 Metadata URL should not be performed.
--project-ref <string>

Optional

Project ref of the Supabase project.

Remove a connection to an already added SSO identity provider. Removing the provider will prevent existing users from logging in. Please treat this command with care.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Activates the custom hostname configuration for a project.

This reconfigures your Supabase project to respond to requests on your custom hostname.

After the custom hostname is activated, your project's third-party auth providers will no longer function on the Supabase-provisioned subdomain. Please refer to Prepare to activate your domain section in our documentation to learn more about the steps you need to follow.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Create a custom hostname for your Supabase project.

Expects your custom hostname to have a CNAME record to your Supabase project's subdomain.

Flags

--custom-hostname <string>

Required

The custom hostname to use for your Supabase project.
--project-ref <string>

Optional

Project ref of the Supabase project.

Retrieve the custom hostname config for your project, as stored in the Supabase platform.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Activate a vanity subdomain for your Supabase project.

This reconfigures your Supabase project to respond to requests on your vanity subdomain. After the vanity subdomain is activated, your project's auth services will no longer function on the {project-ref}.{supabase-domain} hostname.

Flags

--desired-subdomain <string>

Required

The desired vanity subdomain to use for your Supabase project.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--desired-subdomain <string>

Required

The desired vanity subdomain to use for your Supabase project.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Deletes the vanity subdomain for a project, and reverts to using the project ref for routing.

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Network bans are IPs that get temporarily blocked if their traffic pattern looks abusive (e.g. multiple failed auth attempts).

The subcommands help you view the current bans, and unblock IPs if desired.

Subcommands

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--db-unban-ip <strings>

Optional

IP to allow DB connections from.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--append

Optional

Append to existing restrictions instead of replacing them.
--bypass-cidr-checks

Optional

Bypass some of the CIDR validation checks.
--db-allow-cidr <strings>

Optional

CIDR to allow DB connections from.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--disable-db-ssl-enforcement

Optional

Whether the DB should disable SSL enforcement for all external connections.
--enable-db-ssl-enforcement

Optional

Whether the DB should enable SSL enforcement for all external connections.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Flags

--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Overriding the default Postgres config could result in unstable database behavior. Custom configuration also overrides the optimizations generated based on the compute add-ons in use.

Flags

--config <strings>

Optional

Config overrides specified as a 'key=value' pair
--no-restart

Optional

Do not restart the database after updating config.
--replace-existing-overrides

Optional

If true, replaces all existing overrides with the ones provided. If false (default), merges existing overrides with the ones provided.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

Delete specific config overrides, reverting them to their default values.

Flags

--config <strings>

Optional

Config keys to delete (comma-separated)
--no-restart

Optional

Do not restart the database after deleting config.
--experimental

Required

enable experimental features
--project-ref <string>

Optional

Project ref of the Supabase project.

List all SQL snippets of the linked project.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Download contents of the specified SQL snippet.

Flags

--project-ref <string>

Optional

Project ref of the Supabase project.

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(supabase completion zsh)

To load completions for every new session, execute once:

Linux:

supabase completion zsh > "${fpath[1]}/_supabase"

macOS:

supabase completion zsh > $(brew --prefix)/share/zsh/site-functions/_supabase

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions

Optional

disable completion descriptions

Generate the autocompletion script for powershell.

To load completions in your current shell session:

supabase completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

Flags

--no-descriptions

Optional

disable completion descriptions

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

supabase completion fish | source

To load completions for every new session, execute once:

supabase completion fish > ~/.config/fish/completions/supabase.fish

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions

Optional

disable completion descriptions

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(supabase completion bash)

To load completions for every new session, execute once:

Linux:

supabase completion bash > /etc/bash_completion.d/supabase

macOS:

supabase completion bash > $(brew --prefix)/etc/bash_completion.d/supabase

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions

Optional

disable completion descriptions

4%8,548 words