The full Supabase Management API (108 endpoints) plus a local SQLite cache of orgs, projects, functions, branches, and secret names — powering cross-project queries no live API answers in one call, with Auth Admin lookup and PostgREST schema introspection on top.
The official Supabase CLI is local-dev tooling (Docker, migrations, types). This CLI is the API-surface companion, with --json --select --dry-run consistency across every command. Cross-project queries (secrets where-name STRIPE_KEY, branches drift --older-than 7d, functions inventory --org acme) operate over the local store; auth-admin lookup, pgrst schema, and storage usage hit live project APIs.
Known Gaps (see ## Known Gaps below): hand-written Auth Admin user CRUD, Storage object lifecycle, PostgREST row CRUD, Edge Function runtime invoke. Use supabase-js or the Supabase dashboard for those until a follow-up polish session adds them.
Printed by @giacaglia (Giuliano Giacaglia).
Authentication
Supabase has three credential types across two API hosts. The Management API at api.supabase.com uses a Personal Access Token (SUPABASE_ACCESS_TOKEN, header Authorization: Bearer <PAT>). Project APIs at <ref>.supabase.co use the apikey: header — set SUPABASE_PUBLISHABLE_KEY (or legacy SUPABASE_ANON_KEY) for RLS-respecting calls, or SUPABASE_SERVICE_ROLE_KEY (or new SUPABASE_SECRET_KEY) for server-side calls that bypass RLS and unlock Auth Admin endpoints. Also set SUPABASE_URL=https://<ref>.supabase.co. Edge Functions gotcha: keys go in apikey:, never Authorization: Bearer.
Quick Start
# Verify both Management and project credentials are wired and reachable.
supabase-pp-cli doctor
# List your organizations via the Management API (requires SUPABASE_ACCESS_TOKEN).
supabase-pp-cli organizations list-all --json
# Populate the local SQLite store with orgs/projects/functions/branches/secrets.
supabase-pp-cli sync --json
# Cross-project audit: every project holding the named secret (local SQL).
supabase-pp-cli secrets where-name STRIPE_KEY --json
# Fetch the per-project PostgREST schema via Management API (replacement for the anon-key path being removed April 2026).
supabase-pp-cli pgrst schema --table profiles --json
Unique Features
These capabilities aren't available in any other tool for this API.
Cross-project rollups
-
secrets where-name — Find every project (across orgs) holding a secret with a given name, plus when each was last synced.
Use when an agent needs cross-project security posture answers ('which clients have STRIPE_KEY', 'is this secret name leaked anywhere'). The supabase-community MCP cannot answer this without per-project iteration.
supabase-pp-cli secrets where-name STRIPE_KEY --json
-
functions inventory — Per-project, per-org rollup of every edge function with slug, version, status, and last-deployed timestamp.
Use during deploy review ('which projects deployed stripe-webhook?') or stale-function audits ('which functions haven't redeployed in 90 days?').
supabase-pp-cli functions inventory --org acme --json
-
branches drift — List preview branches older than N days that haven't been merged or deleted, grouped by parent project.
Use during weekly cleanup to prevent preview-branch sprawl that costs DB resources.
supabase-pp-cli branches drift --older-than 7d --json
-
projects estate — One-row-per-project rollup of function count, branch count, api-key count, secret-name count, and last-synced-at.
Use for the Monday morning estate review; one screen replaces 12 dashboard tabs.
supabase-pp-cli projects estate --json
-
auth-admin recent — Iterate synced projects, call Auth Admin per project, aggregate users created within the window into one table.
Use for weekly user-growth review across an entire org portfolio.
supabase-pp-cli auth-admin recent --since 7d --json
Service-specific patterns
-
auth-admin lookup — Look up an Auth user by email and optionally join their row from a user-named PostgREST context table on user_id.
Use during support-ticket triage to see the user plus their domain row in one envelope instead of three dashboard clicks.
supabase-pp-cli auth-admin lookup user@example.com --context-table profiles --context-key user_id --json
-
pgrst schema — Fetch the per-project PostgREST OpenAPI from the Management API and list tables, columns, types, and detected indexes for typed query planning.
Use before authoring a typed query so an agent knows the table's column types and constraints without trial-and-error.
supabase-pp-cli pgrst schema --table profiles --json
-
storage usage — For each bucket, list objects and aggregate file count, total bytes, and largest object.
Use when an agent needs to answer 'how close are we to the storage ceiling' or 'which bucket is biggest'.
supabase-pp-cli storage usage --bucket avatars --json
Known Gaps
These project-surface command groups were planned in the absorb manifest but deferred from this initial build (Phase 3 scope contraction). Use supabase-js or the Supabase dashboard for them until a follow-up polish session lands them:
- Auth Admin user CRUD — bulk create, invite, update, delete users + MFA factor management.
auth-admin lookup and auth-admin recent (cross-project signup window) DO ship; this gap covers the write side.
- Storage object lifecycle — upload, download, signed URL generation, move, copy, delete.
storage usage (per-bucket size/count rollup) DOES ship; this gap covers object-level CRUD.
- PostgREST row CRUD —
pgrst select / insert / upsert / delete against user-defined tables. pgrst schema (typed schema fetch via Management API) DOES ship; row CRUD is deferred.
- Edge Function runtime invocation —
POST /functions/v1/<name> with body. Function lifecycle (deploy/list/get) is available via projects functions ... from the Management API mirror; the runtime invoke wrapper is deferred.
- Realtime WebSocket subscribe — permanently out of scope (WebSocket doesn't fit a one-shot CLI shape).
Workarounds: for PostgREST row queries, curl https://<ref>.supabase.co/rest/v1/<table>?<filter> -H 'apikey: $SUPABASE_PUBLISHABLE_KEY' -H 'Authorization: Bearer $SUPABASE_PUBLISHABLE_KEY' or the supabase-js PostgREST builder. For Storage object operations, supabase-js's storage client. For Edge Function invoke, curl https://<ref>.supabase.co/functions/v1/<name> -H 'apikey: $SUPABASE_PUBLISHABLE_KEY' -d <body>.
Usage
Run supabase-pp-cli --help for the full command reference and flag list.
Commands
branches
Manage branches
supabase-pp-cli branches delete-a-branch - Deletes the specified database branch. By default, deletes immediately. Use force=false to schedule deletion with 1-hour grace period (only when soft deletion is enabled).supabase-pp-cli branches get-a-branch-config - Fetches configurations of the specified database branchsupabase-pp-cli branches update-a-branch-config - Updates the configuration of the specified database branch
oauth
OAuth related endpoints
supabase-pp-cli oauth authorize-project-claim - Initiates the OAuth authorization flow for the specified provider. After successful authentication, the user can claim ownership of the specified project.supabase-pp-cli oauth authorize-user - [Beta] Authorize user through oauthsupabase-pp-cli oauth exchange-token - [Beta] Exchange auth code for user's access and refresh tokensupabase-pp-cli oauth revoke-token - [Beta] Revoke oauth app authorization and it's corresponding tokens
organizations
Organizations related endpoints
supabase-pp-cli organizations create-an - Create an organizationsupabase-pp-cli organizations get-an - Gets information about the organizationsupabase-pp-cli organizations list-all - Returns a list of organizations that you currently belong to.
projects
Projects related endpoints
supabase-pp-cli projects create-a - Create a projectsupabase-pp-cli projects delete-a - Deletes the given projectsupabase-pp-cli projects get - Gets a specific project that belongs to the authenticated usersupabase-pp-cli projects get-available-regions - [Beta] Gets the list of available regions that can be used for a new projectsupabase-pp-cli projects list-all - Returns a list of all projects you've previously created.supabase-pp-cli projects update-a - Updates the given project
snippets
Manage snippets
supabase-pp-cli snippets get-a - Gets a specific SQL snippetsupabase-pp-cli snippets list-all - Lists SQL snippets for the logged in user
supabase-profile
Manage supabase profile
supabase-pp-cli supabase-profile get - Gets the user's profile
Output Formats
# Human-readable table (default in terminal, JSON when piped)
supabase-pp-cli projects get mock-value
# JSON for scripting and agents
supabase-pp-cli projects get mock-value --json
# Filter to specific fields
supabase-pp-cli projects get mock-value --json --select id,name,status
# Dry run — show the request without sending
supabase-pp-cli projects get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
supabase-pp-cli projects get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
supabase-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/supabase-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SUPABASE_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
supabase-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SUPABASE_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized on Auth Admin or RLS-bypassing PostgREST calls — These endpoints require the service_role key. Set
SUPABASE_SERVICE_ROLE_KEY (or new SUPABASE_SECRET_KEY); the publishable/anon key is RLS-only.
- 401 Unauthorized on Edge Function invoke — Keys go in the
apikey: header, not Authorization: Bearer. The CLI sets this correctly by default; check that you haven't overridden the auth header via --header.
- 403 Forbidden on Management API — Management API needs a Personal Access Token (sbp_...), not a project key. Generate one at supabase.com/dashboard/account/tokens and
export SUPABASE_ACCESS_TOKEN=....
- Empty results from
pgrst select despite knowing rows exist — Row-Level Security is filtering them out. Either use the service_role key (bypasses RLS) or sign in as a user whose JWT passes the table's RLS policy.
branches drift returns nothing — Sync at least once: supabase-pp-cli sync populates the local store. Drift compares synced rows to filter conditions; an empty store has nothing to compare.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press