supa — Supabase CLI

A standalone CLI for Supabase. Inspect tables, execute SQL, manage schemas, auth, storage, and more — directly from the command line.

Connects directly to your Supabase instance via PostgreSQL. No MCP server required. Works with self-hosted and cloud Supabase.

Install

npm install -g leadgrow-supa-cli

Setup

supa setup

Interactive wizard that configures:

1. PostgreSQL connection string
2. Supabase project URL
3. API keys (anon + optional service role)
4. MCP auto-config for Claude Desktop, Claude Code, and Cursor

Or set environment variables directly:

export DATABASE_URL="postgresql://postgres:password@localhost:54322/postgres"
export SUPABASE_URL="http://localhost:54321"
export SUPABASE_ANON_KEY="eyJ..."
export SUPABASE_SERVICE_ROLE_KEY="eyJ..."  # optional

Commands

SQL Execution

supa sql "SELECT * FROM users LIMIT 10"
supa sql -f query.sql
cat query.sql | supa sql

Table Inspection

supa tables                        # List all tables and views
supa tables -s public              # Filter by schema
supa tables --tables-only          # Exclude views
supa describe users                # Columns, indexes, FKs, RLS, sizes
supa describe leadgrow.campaigns   # Schema-qualified

Table DDL

supa table create users --columns "id:uuid:primary:default(gen_random_uuid()),name:text:not_null,email:text:unique,created_at:timestamptz:default(now())"
supa table create users --enable-rls --if-not-exists
supa table add-column users avatar text
supa table drop-column users avatar --cascade
supa table rename users people
supa table drop old_table --if-exists

Column spec format: name:type[:constraint1[:constraint2]]

Types: uuid, text, int4, int8, bool, timestamptz, jsonb, float8, varchar, etc.

Constraints: primary, not_null, unique, default(expr), references(table.col)

Schema Inspection

supa schemas                       # List schemas
supa functions                     # List functions/procedures
supa functions -s public           # Filter by schema
supa indexes                       # List all indexes
supa indexes users                 # Indexes for a specific table
supa rls                           # List all RLS policies
supa rls users                     # RLS policies for a table
supa extensions                    # List installed extensions
supa types                         # List custom types and enums
supa types --enums-only            # Enums only

Database Monitoring

supa stats                         # Database statistics
supa stats --table-stats           # Per-table statistics
supa connections                   # Active connections
supa connections --all             # Include background workers

Migrations

supa migrate list                  # List applied migrations
supa migrate apply migration.sql   # Apply a migration file
supa migrate apply migration.sql --dry-run  # Preview without executing
supa migrate scan ./migrations     # Compare local files with applied

Auth (read-only)

supa auth list                     # List auth users
supa auth list --per-page 100      # Paginate
supa auth get <user-id>            # Get user details

Requires service role key for auth admin operations.

Storage (read-only)

supa storage buckets               # List storage buckets
supa storage ls <bucket>           # List objects in a bucket
supa storage ls <bucket> --prefix images/

Configuration

supa config show                   # Show current config
supa config set --database-url URL # Set a value
supa config reset                  # Reset to defaults
supa config path                   # Print config file path

Global Flags

Every command supports these flags:

| Flag | Description | |------|-------------| | --json | Output raw JSON (agent-friendly) | | --fields <fields> | Comma-separated fields to display | | --quiet | Suppress output, exit code only | | -h, --help | Show help for any command | | -V, --version | Show version |

Agent / AI Integration

Via Shell (simplest)

Any AI agent with shell access can use supa commands directly. Always use --json for structured output:

supa tables --json
supa describe users --json
supa sql "SELECT count(*) FROM orders" --json

Run supa docs to get the full CLI reference — useful for injecting into agent context.

Via MCP

The CLI includes a built-in MCP (Model Context Protocol) stdio server with 17 tools:

supa mcp          # Start MCP server
supa mcp status   # Check MCP config status

Add to ~/.claude/mcp_servers.json for Claude Code:

{
  "mcpServers": {
    "supabase": {
      "command": "supa",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "SUPABASE_URL": "https://...",
        "SUPABASE_ANON_KEY": "eyJ..."
      }
    }
  }
}

Or run supa setup and select yes for MCP auto-configuration.

Configuration

Config file: ~/.supa/config.json

Environment variables override the config file:

| Variable | Description | |----------|-------------| | DATABASE_URL | PostgreSQL connection string | | SUPABASE_URL | Supabase project URL | | SUPABASE_ANON_KEY | Anonymous key | | SUPABASE_SERVICE_ROLE_KEY | Service role key (optional) |

License

MIT