pp-supabase

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/developer-tools/supabase/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Supabase — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `supabase-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install supabase --cli-only
   ```
2. Verify: `supabase-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/developer-tools/supabase/cmd/supabase-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when an agent needs to sweep Management API entities across orgs, run cross-project queries from a local SQLite cache (`secrets where-name`, `functions inventory`, `branches drift`, `projects estate`), look up Auth users by email (`auth-admin lookup`), aggregate Storage bucket usage (`storage usage`), or fetch a per-project PostgREST schema for typed query planning (`pgrst schema`).

For local Docker + migration workflows (`supabase start`, `supabase db push`, `supabase gen types`), use the official Supabase CLI. For PostgREST row CRUD, Storage object lifecycle (upload/download/sign), Auth Admin user mutations, and Edge Function runtime invocation, use `supabase-js` — these are documented Known Gaps in this CLI's first release (see README's `## Known Gaps`).

## Unique Capabilities

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._

  ```bash
  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?')._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  supabase-pp-cli auth-admin lookup [email protected] --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._

  ```bash
  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'._

  ```bash
  supabase-pp-cli storage usage --bucket avatars --json
  ```

## Command Reference

**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...
- `supabase-pp-cli branches get-a-branch-config` — Fetches configurations of the specified database branch
- `supabase-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...
- `supabase-pp-cli oauth authorize-user` — [Beta] Authorize user through oauth
- `supabase-pp-cli oauth exchange-token` — [Beta] Exchange auth code for user's access and refresh token
- `supabase-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 organization
- `supabase-pp-cli organizations get-an` — Gets information about the organization
- `supabase-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 project
- `supabase-pp-cli projects delete-a` — Deletes the given project
- `supabase-pp-cli projects get` — Gets a specific project that belongs to the authenticated user
- `supabase-pp-cli projects get-available-regions` — [Beta] Gets the list of available regions that can be used for a new project
- `supabase-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 snippet
- `supabase-pp-cli snippets list-all` — Lists SQL snippets for the logged in user

**supabase-profile** — Manage supabase profile

- `supabase-pp-cli supabase-profile` — Gets the user's profile


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
supabase-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Cross-project secret audit

```bash
supabase-pp-cli sync && supabase-pp-cli secrets where-name STRIPE_KEY --json
```

Sync the local store, then list every project across every org holding a secret named STRIPE_KEY — the Monday-morning security sweep in one shell call.

### Support ticket triage

```bash
supabase-pp-cli auth-admin lookup [email protected] -