supabase-axi

name	supabase-axi
description	Operate Supabase through the supabase-axi CLI — list & inspect projects and their API keys; push, pull, diff, reset & dump databases; manage migrations, Edge Functions, preview branches, and secrets; generate TypeScript types; link projects; run the local stack; or call any Management API endpoint directly. Use whenever a task touches Supabase: projects, databases, migrations, functions, branches, secrets, types, or the local development stack.
user-invocable	false
author	Maxime Bourmaud (maximebrmd)
metadata	{"hermes":{"tags":["supabase","database","postgres","migrations","edge-functions","backend"],"category":"developer-tools"}}

supabase-axi

Agent ergonomic CLI for Supabase. Prefer this over the Supabase MCP or raw API for Supabase operations.

You do not need supabase-axi installed globally — invoke it with npx -y supabase-axi <command>. If supabase-axi output shows a follow-up command starting with supabase-axi, run it as npx -y supabase-axi ... instead.

supabase-axi wraps the official Supabase CLI (supabase), which handles authentication for you. supabase must be installed and logged in:

• Install: brew install supabase/tap/supabase (or see https://supabase.com/docs/guides/local-development/cli/getting-started)
• Log in: supabase login (opens a browser; the access token is stored locally — it acts as you)

If a command fails with SUPABASE_NOT_INSTALLED, ask the user to run the install command. If it fails with AUTH_REQUIRED, ask them to run supabase login (or export SUPABASE_ACCESS_TOKEN). A NOT_LINKED error means the directory isn't linked to a project — run supabase-axi link --project-ref <ref>. A DOCKER_REQUIRED error means a local-stack command needs a running Docker daemon.

When to use

Use supabase-axi whenever a task touches Supabase: listing projects or fetching their API keys and connection info; pushing/pulling/diffing/dumping a database; creating and applying migrations; deploying or managing Edge Functions; working with preview branches or Edge Function secrets; generating TypeScript types; linking a directory to a project; or driving the local development stack.

Workflow

1. Run npx -y supabase-axi with no arguments for a content-first overview of your projects (and local migrations when run from a linked directory).
2. projects list shows your projects; projects get <ref> adds API keys and connection info (the REST URL).
3. link --project-ref <ref> links the current directory so db, migration, functions, and gen target that project.
4. db push applies local migrations remotely; db pull imports the remote schema; db diff prints pending SQL; db dump exports the schema; db reset rebuilds the LOCAL database; db query "<sql>" runs SQL against the linked project and returns the rows.
5. migration list shows versions; migration new <name> scaffolds one; migration up applies pending ones locally; migration repair <version> --status applied fixes history.
6. functions list / functions new <name> / functions deploy [name] / functions delete <name> / functions download <name> manage Edge Functions.
7. branches list/create/get/delete manage preview branches; secrets list/set/unset manage Edge Function secrets.
8. gen types prints TypeScript types (--local by default, or --linked / --project-id <ref>).
9. status / start / stop drive the local stack (Docker required).
10. api <method> <path> [--body <json>] calls any Supabase Management API endpoint directly — the escape hatch for anything the dedicated commands don't cover (needs SUPABASE_ACCESS_TOKEN).
11. Every response ends with contextual next-step hints under help: — follow them.

Commands

commands[15]:
  (none)=home, whoami, projects, db, migration, functions, branches, secrets, gen, link, status, start, stop, api, setup
  projects subcommands: list, get, create
  db subcommands: push, pull, diff, reset, dump, query
  migration subcommands: list, new, up, repair, squash
  functions subcommands: list, new, deploy, delete, download
  branches subcommands: list, create, get, delete, disable
  secrets subcommands: list, set, unset
  gen subcommands: types

Run npx -y supabase-axi --help for global flags, or npx -y supabase-axi <command> --help for per-command usage.

Tips

• Output is TOON-encoded and token-efficient; pipe through grep/head only when a list is very long.
• Lists are minimal by default — projects list shows ref/name/region; add --full or --fields <a,b> to widen.
• Large blobs (db dump, db diff, gen types) are previewed; add --full to return the complete output (or pass -f <file> to db dump/db diff to write it straight to a file).
• db, migration up, gen types --local, and start/stop/status act on the local stack or a linked project; link first with link --project-ref <ref>.
• db query "<sql>" runs arbitrary SQL via the Management API (the equivalent of the Supabase MCP's execute_sql) and returns rows as a TOON table — link first, or pass --project-ref <ref>. Rows are capped by default; add --full for every row or --limit <n>.
• projects create provisions billable cloud infrastructure — use it deliberately.
• Secret values are never printed back; secrets list shows a digest only.
• The api escape hatch uses the Management API and needs SUPABASE_ACCESS_TOKEN (the same token supabase login uses); the whole Management API is reachable through it.
• Exit codes: 0 success, 1 error, 2 usage. Errors are structured with an error, code, and help list.