---
name: supabase
description: Interact with Supabase projects via Management API and direct Postgres connections. Manage projects, databases, tables, auth, edge functions, and storage.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [Supabase, Database, Postgres, Auth, API]
---

# Supabase Management

Use this skill when the user wants to manage Supabase projects, interact with databases, manage auth, storage, or edge functions.

## Authentication

### Management API
Uses the Supabase personal access token (starts with `sbp_`).
```bash
SUPABASE_ACCESS_TOKEN="sbp_..."
```

### Project API Keys
Each project has API keys in Settings > API:
- **anon public** (`anon`) — Safe for client-side use, RLS applies
- **service_role** (`service_role`) — Bypasses RLS, NEVER expose to client

### Direct Database Connection
Connect directly via psql using the Postgres connection string:
```bash
psql "postgresql://postgres.<project_ref>:<db_password>@db.<project_ref>.supabase.co:6543/postgres"
```

## Management API (via curl)

All API calls use:
```bash
export SUPABASE_ACCESS_TOKEN="sbp_..."
```

### Projects
```bash
# List projects
curl -s https://api.supabase.com/v1/projects -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

# Get project details
curl -s https://api.supabase.com/v1/projects/<project_ref> -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

### Database
```bash
# Get connection details
curl -s https://api.supabase.com/v1/projects/<project_ref>/endpoints -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

# Run a SQL query (via REST API - limited)
# Better to use direct connection with psql for complex queries
```

### Auth (Users)
Via project REST API:
```bash
export PROJECT_URL="https://<project_ref>.supabase.co"
export SERVICE_ROLE_KEY="<service_role_key>"

# List users
curl -s "$PROJECT_URL/auth/v1/users" \
  -H "apikey: $SERVICE_ROLE_KEY" \
  -H "Authorization: Bearer $SERVICE_ROLE_KEY"

# Get a user
curl -s "$PROJECT_URL/auth/v1/users/<user_id>" \
  -H "apikey: $SERVICE_ROLE_KEY" \
  -H "Authorization: Bearer $SERVICE_ROLE_KEY"
```

### Storage
```bash
# List buckets
curl -s "$PROJECT_URL/storage/v1/buckets" \
  -H "apikey: $SERVICE_ROLE_KEY" \
  -H "Authorization: Bearer $SERVICE_ROLE_KEY"
```

### Edge Functions
```bash
# List functions via management API
curl -s "https://api.supabase.com/v1/projects/<project_ref>/functions" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

## Direct Database Connection (psql)

For full SQL access, connect directly:
```bash
psql -h db.<project_ref>.supabase.co -p 6543 -U postgres.<project_ref> -d postgres
# Will prompt for database password (set in project Settings > Database)
```

Or via connection string:
```bash
psql "postgresql://postgres.<project_ref>:DB_PASSWORD@db.<project_ref>.supabase.co:6543/postgres"
```

## Common Tasks

### Inspect tables
Use psql to connect, then:
```sql
\dt                    -- list tables
\d table_name          -- describe table schema
SELECT * FROM table_name LIMIT 10;  -- preview data
```

### Check project health
```bash
curl -s https://api.supabase.com/v1/projects/<project_ref> \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"
```

## Notes

- Management API token (`sbp_`) is for project-level operations (list, create, manage)
- Service role key is for database/auth operations within a project
- Always prefer psql for database work — it's faster and more reliable
- Region matters: sa-east-1 is Brazil (closest to Argentina), us-east-1 is Virginia