Skip to content

About

A proper CLI to do all things Supabase when self hosting

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Supabase Selfhosted CLI

CLI for self hosted Supabase for a VPS, in Docker on a remote server, or running locally on your machine.

So you've figured out how to use the port numbers to push migrations and sync types using the regular Supabase CLI. And credit where credit is due, Supabase really does work quite well with the " - db-url" flag. However, the entire process leaves something to be desired. Especially when dealing with real-time edge functions, as you have to keep tossing in the scp command with the right path, type in the VPS password and then restart the docker container.

This thing will wrap up the repetitive work you do by hand: deploy edge functions, restart the runtime, push migrations, and regenerate TypeScript types.

As featured on https://spyke.social

Supabase Selfhosted CLI Screenshot

Install

yarn global add supabase-selfhosted-cli

or

npm install -g supabase-selfhosted-cli

Or run from source:

git clone https://github.com/spykesocial/supabase-selfhosted-cli.git
cd supabase-selfhosted-cli
npm install
npm link

You still need the Supabase CLI installed for db push and gen types (this package shells out to it). Supabase CLI also uses docker to create its own copy of the remote instance so you'll need docker installed when generating types.

Quick start

From your project root (where supabase/migrations lives):

supabase-selfhosted-cli

or if you just want to setup

supabase-selfhosted-cli setup

The wizard asks where your instance runs:

  • Local machine — Docker / Docker Compose on this computer (copies files directly to your volume mount, runs restart locally)
  • Remote server — VPS or cloud VM over SSH (SFTP upload + remote restart)

Remote server (VPS) example

Setting Example
SSH user root
Server IP 203.0.113.10
Functions destination /etc/supabase/volumes/functions
SSH password stored once in ~/.supabase-selfhosted-cli/
Postgres tenant id your-tenant-id (from postgres.your-tenant-id)
DB password your pooler password
Migration port 5453
Types port 6438
Restart command e.g. docker restart <edge-container>

Local Docker example

Setting Example
Functions destination /path/to/supabase/docker/volumes/functions (absolute path to your edge-runtime volume mount)
Database host 127.0.0.1
Migration port 5432 (or your exposed Postgres port)
Types port 5432 (or your exposed Postgres pooler port)
Restart command docker compose restart edge-runtime or auto-detect edge container

Setup creates .supabase-selfhosted-cli.json in your project so commands know which environment(s) to use.

Commands

Deploy edge functions

Remote (SSH) — replaces:

scp -r supabase/functions/. root@203.0.113.10:/etc/supabase/volumes/functions
ssh root@203.0.113.10 'docker restart ...'

Local (Docker) — replaces manually copying into your Docker volume and restarting containers.

supabase-selfhosted-cli functions deploy

Flags:

  • --restart — always restart after deploy
  • --no-restart — never restart
  • --prune — remove destination files/folders not present locally (use after deleting a function)
  • default — prompts based on your setup preference

End-to-end verification against a configured project:

npm run build
./scripts/e2e-deploy-test.sh /path/to/your-project

Push migrations

Replaces:

PGSSLMODE=disable npx supabase db push --db-url 'postgresql://postgres.your-tenant-id:...@host:5453/postgres?sslmode=disable' --yes

Self-hosted Supavisor typically has no TLS. Recent Supabase CLI versions require TLS for remote --db-url hosts, so this CLI sets PGSSLMODE=disable (and sslmode=disable on the URL). That is also why bare npx supabase db push --db-url ... fails with tls error (server refused TLS connection) while the same command with --debug succeeds.

db push also runs a migration-privilege preflight (supabase/cli#3531). The Supabase CLI runs CREATE SCHEMA IF NOT EXISTS supabase_migrations on every push, and PostgreSQL 15+ requires CREATE on the database for it — checked before the "already exists" skip — so a single missing grant fails every push of every project. When the role lacks it, this CLI grants it once (via docker exec <db-container> psql -U supabase_admin on your SSH target — the db container is found by its published port, never by name) and then pushes. When it cannot, it prints the exact SQL to run instead of the bare Go error.

supabase-selfhosted-cli db push
supabase-selfhosted-cli db push --debug

Generate TypeScript types

Replaces:

PGSSLMODE=disable npx supabase gen types typescript --db-url 'postgresql://...@host:6438/postgres?sslmode=disable' --schema public > database.types.ts
supabase-selfhosted-cli gen types
supabase-selfhosted-cli gen types -o database.types.ts

Manage credentials

supabase-selfhosted-cli settings
  • Show masked configuration
  • Re-run setup wizard
  • Delete stored credentials

Configuration storage

  • Environments: ~/.supabase-selfhosted-cli/profiles/<name>.json (mode 600)
  • Project link: .supabase-selfhosted-cli.json in your repo

Passwords are stored locally on your machine. Delete them anytime via supabase-selfhosted-cli settings.

Multiple projects / environments

One repo can link to multiple environments (for example development and production). Credentials live in ~/.supabase-selfhosted-cli/profiles/; the project link file stores the linked set plus which environment is active.

.supabase-selfhosted-cli.json shape:

{
  "environments": ["development", "production"],
  "projectId": "<uuid>"
}

Legacy single-field { "profile": "…" } and multi-field { "profiles": […] } links still work and upgrade automatically.

From a project directory:

# See linked projects and environments
supabase-selfhosted-cli projects --list

# First time — creates an environment (folder name, or pick development / production)
supabase-selfhosted-cli setup

# Add another environment without replacing the first
supabase-selfhosted-cli projects --link

# Change which environment commands use by default
supabase-selfhosted-cli projects --switch

# Edit SSH/DB credentials for an environment
supabase-selfhosted-cli projects --edit

# Remove stored credentials for an environment
supabase-selfhosted-cli projects --delete

Use -e to target an environment for a single command (does not change the active default):

supabase-selfhosted-cli setup --environment production
supabase-selfhosted-cli db push --environment production
supabase-selfhosted-cli functions deploy --environment production

Restart command tips

Self-hosted setups differ. During setup, the CLI suggests a mount-scoped restart command derived from your functions path. It finds the edge-functions container that mounts that exact path — important on Dokploy/Coolify, where the compose folder id can differ from the Docker container name (e.g. folder ...-oy2cqz vs container ...-8rcgv9-supabase-edge-functions).

# Mount-scoped (recommended; auto-suggested)
# Finds the container whose volume source is your functions path, then restarts it.

# Explicit container name (if you already know it)
docker restart financial-wisdom-supabase-8rcgv9-supabase-edge-functions

# Docker Compose from that stack's directory
cd /etc/dokploy/compose/financial-wisdom-supabase-oy2cqz && docker compose restart

Avoid host-wide greps like grep -i edge | head -n 1 when the server runs multiple Supabase projects.

Troubleshooting

The known failures of self-hosted Supavisor setups, what they actually mean, and the fix — db push prints these automatically when it recognizes the error:

Symptom Cause Fix
failed to create migration table: ERROR: permission denied for database PG15+ needs CREATE on the database for the CLI's CREATE SCHEMA IF NOT EXISTS — even when the schema exists (supabase/cli#3531) Granted automatically by the db push preflight. Manually, once per database, as a superuser (Studio SQL editor or docker exec <db-container> psql -U supabase_admin): GRANT CREATE ON DATABASE postgres TO postgres;
prepared statement "…" already exists Supavisor/pgbouncer transaction pooling vs. the Supabase CLI's prepared statements Retry (pool state varies), or set the migration port to the stack's direct Postgres port (54xx) rather than the pooler port (64xx)
tls error: server refused TLS connection Self-hosted Supavisor has no TLS Run through this CLI (it sets PGSSLMODE=disable), or prefix the raw command with PGSSLMODE=disable

Roadmap

  • OS keychain integration for secrets
  • Remote environment sync for teams
  • Migration status, function diff, and health checks

License

MIT

About

A proper CLI to do all things Supabase when self hosting

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages