agentlink

Teach AI agents the right way to build on Supabase.

Agent Link is an opinionated skill set for Claude Code — and this CLI is how you start a project with it. One command scaffolds a Supabase backend with schema isolation, RPC-first data access, row-level security, multi-tenancy, and edge functions already wired up — plus a frontend (React + Vite or Next.js) with auth, theming, and shadcn/ui ready to go. Your agent doesn't have to figure out the architecture — it's already there. From that foundation, five domain skills give it one clear path for every decision: how to structure tables, write RLS policies, expose APIs, handle background work, and connect a frontend. No ambiguity, no wrong turns. First-try results.

Install & Run

Install cli globally.

npm i -g agentlink-sh@latest

Or run directly with npx (requires Node.js 18+):

npx agentlink-sh@latest

Quick start

# Create a new project (cloud by default)
agentlink my-app

# With a prompt for Claude Code
agentlink my-app --prompt "Build a project management tool with kanban boards"

# Interactive wizard
agentlink

Commands

agentlink [name]

Interactive wizard that scaffolds a new project or updates an existing one. Uses Supabase Cloud by default — region is auto-detected from your timezone, all recommended skills are installed automatically.

# Interactive wizard
agentlink

# With project name
agentlink my-app

# With prompt (passed to Claude Code on launch)
agentlink my-app --prompt "Build a project management tool"

# Local Docker mode (instead of cloud)
agentlink my-app --local

# NextJS instead of React + Vite
agentlink my-app --nextjs

# Backend only (no frontend)
agentlink my-app --no-frontend

# Skip companion skills
agentlink my-app --no-skills

# Scaffold files only — no Supabase setup. Run `env add dev` later in a
# terminal to finish the env. Use when an agent scaffolds without browser
# access and hands off to the user.
agentlink my-app --skip-env

# Non-interactive (CI-friendly)
agentlink my-app --yes --non-interactive --token $SUPABASE_TOKEN --org $ORG_ID --region us-east-1

Options:

| Flag | Description | | ------------------- | ------------------------------------------------------------------------------------- | | --debug | Write debug log to agentlink-debug.log | | --force-update | Force update even if project is up to date | | --no-frontend | Skip frontend scaffolding (backend only) | | --nextjs | Use NextJS instead of React + Vite | | --local | Use local Docker instead of Supabase Cloud | | --skip-env | Scaffold files without touching Supabase (no OAuth, no project, no Docker, no apply) | | --no-skills | Skip companion skill installation | | --no-launch | Skip launching Claude Code after scaffold | | -y, --yes | Auto-confirm all prompts | | --token <token> | Supabase access token (skips interactive login) | | --org <id> | Supabase organization ID | | --region <region> | Supabase Cloud region (auto-detected if omitted) | | --prompt <prompt> | Alternative to positional prompt argument | | --resume | Resume a previously failed scaffold | | --non-interactive | Error instead of prompting when info is missing | | --link | Link to an existing Supabase project (with --project-ref + connection flags) |

agentlink sb login

Authenticate with Supabase via OAuth (opens browser). Tokens are cached per-org in ~/.config/agentlink/credentials.json and auto-refreshed.

agentlink sb login

The top-level agentlink login / agentlink token commands still work but print a deprecation warning. The top-level login namespace is reserved for future Agent Link accounts.

agentlink sb token

Show or set the Supabase personal access token (PAT) used for non-interactive CI/CD.

agentlink sb token show           # Print the current token and its source
agentlink sb token set sbp_...    # Save a new token

agentlink env

Manage project environments. Agent Link enforces a fixed local → dev → prod model — no custom names (staging, dev2, etc. are rejected).

env add [name]

Add a cloud environment and (by default) deploy the current schema + functions to it. If [name] is omitted, a picker shows dev / prod with a — linked to <projectRef> / — not linked hint per row.

agentlink env add              # Interactive picker
agentlink env add dev          # Connect the dev cloud environment
agentlink env add prod         # Connect production. Does NOT touch .env.local.
agentlink env add dev --no-deploy    # Register the env but skip the initial deploy
agentlink env add dev --setup-ci     # Also scaffold a GitHub Actions workflow

If the environment already exists, env add prompts with a 3-way menu:

  If you just changed schemas or functions, cancel and run `agentlink env deploy <name>` instead.

? Environment "dev" already exists. What would you like to do?
❯ Re-apply full setup — schemas, functions, secrets, PostgREST + auth config
  Relink to a different Supabase project
  Cancel

Re-apply full setup re-runs the full bootstrap (schemas + functions + vault + PostgREST + auth + verify). Use it when auth providers, PostgREST config, or vault secrets changed — otherwise prefer env deploy (lighter, idempotent).

env use [name]

Switch the active environment. Rewrites the managed block in .env.local and updates manifest.cloud.default. If [name] is omitted, a picker lists dev / prod (and local when the project is local-only or already on local) with a ✓ next to the active env.

agentlink env use              # Interactive picker
agentlink env use dev          # Switch to dev
agentlink env use local        # Switch to local Docker
agentlink env use prod         # Switch to prod (requires y/N confirmation)

env use prod prints an amber warning and requires explicit confirmation before writing .env.local — any app or test you run locally will hit production data. After confirming, subsequent env deploy / db apply / db sql / db rebuild invocations print an ▲ Active env: prod banner as a reminder.

env deploy [name]

Apply schemas (db apply) and deploy edge functions to the chosen env. Idempotent. Does NOT mutate manifest.cloud.default — deploy is a one-shot action, so env use dev && env deploy prod stays on dev afterwards.

agentlink env deploy              # Interactive picker (preselects cloud.default)
agentlink env deploy dev          # Deploy to dev
agentlink env deploy prod         # Deploy to prod (requires y/N confirmation)
agentlink env deploy prod --yes   # Skip the confirmation (for CI)
agentlink env deploy dev --dry-run  # Print the target without applying

Auth providers / PostgREST config / vault secrets are NOT touched by env deploy — those are configured during initial env add. If any of those changed, use env add <name> → Re-apply full setup instead.

Generated CI workflows (env add --setup-ci) call env deploy <name> --yes --non-interactive.

env list

Show all configured environments with their org, project ref, and which one is currently active.

agentlink env list

env remove <name>

Remove an environment from agentlink.json. Offers to also wipe the stored DB password for that project.

agentlink env remove prod
agentlink env remove prod -y   # Skip confirmations

The previous agentlink env relink <name> command still works but prints a deprecation warning — use env add <name> (with the env already registered) and pick Relink to a different Supabase project. The top-level agentlink deploy command has been removed entirely; use agentlink env deploy instead.

agentlink check

Verify project setup. Outputs JSON with diagnostic info: ready, supabase_running, database state (extensions, queues, functions, secrets, api_schema), and file checks.

agentlink check
agentlink check --env prod    # Check a specific cloud env

agentlink info [name]

Show documentation about scaffolded components. Without a name, lists all components. With a name, shows type, summary, description, signature, and related components.

agentlink info                # List all components
agentlink info tenant_select  # Detail for one component

agentlink db

Database operations. Every subcommand targets the active cloud env (manifest.cloud.default) unless --env <name> or --db-url <url> is passed.

db apply

Apply all schema files in supabase/schemas/ to the database using pg-delta declarative apply. Generates TypeScript types afterwards unless --skip-types is set.

agentlink db apply
agentlink db apply --skip-types
agentlink db apply --env prod
agentlink db apply --db-url postgresql://...

db migrate <name>

Generate a migration file from the diff between the current database state and the schema files. Intended for creating auditable deployment artifacts — env deploy does NOT generate migrations.

agentlink db migrate add_charts_table
agentlink db migrate add_charts_table --env prod

db sql <query>

Run ad-hoc SQL against the active database. Uses psql locally, Management API for cloud.

agentlink db sql "SELECT count(*) FROM public.profiles"
agentlink db sql "SELECT * FROM api.chart_list()" --json
agentlink db sql "..." --env prod

db types

Regenerate src/types/database.ts (Vite) or types/database.ts (Next.js) from the api schema.

agentlink db types
agentlink db types --output custom/path.ts

db rebuild

Nuke supabase/migrations/*, re-apply schemas, and regenerate a single baseline migration. Recovery path when migration state gets broken early in a project.

agentlink db rebuild

db url [--fix]

Show the correct pooler DB URL for the active cloud env. --fix updates .env.local if the current value is stale.

agentlink db url
agentlink db url --fix

db password [value]

Show or set the stored DB password for the active cloud env's project.

agentlink db password                 # Prompt (masked) + save
agentlink db password "new-password"  # Set directly

db backup

Snapshot the current env's database into three SQL files following Supabase's recommended db dump triplet — roles.sql (role-only), schema.sql (definitions), and data.sql (COPY-formatted data, with the storage.buckets_vectors / storage.vector_indexes tables excluded). Files are written to supabase/backups/<env>/<YYYY-MM-DDTHH-MM-SS>/; each run creates a fresh timestamped subdirectory so previous snapshots are preserved.

On first run, supabase/backups/ is appended to the project's root .gitignore under an "Agent Link — database backups" comment. Idempotent on re-runs. Snapshots may contain real production data, so they're gitignored by default.

agentlink db backup                    # Active env (cloud.default, or local if none)
agentlink db backup --env prod         # Target prod explicitly (shows ▲ Active env: prod if active)
agentlink db backup --db-url "postgresql://..."  # Override URL entirely

Works on cloud envs, local Docker, and bare projects — doesn't require supabase/schemas/ or any scaffolded files, just a reachable DB. Read-only; no cloud mutation.

agentlink env config [subcommand] [env-name]

Apply one or more server-side config sections to a cloud env. The three subsystems are independent — run just the one that drifted, or all for a full re-apply. Same primitives used by env add's initial bootstrap, so there's no config drift between first-time setup and re-applies.

| Subcommand | What it does | |-----------|--------------| | secrets | Seed Vault (SUPABASE_URL / SUPABASE_PUBLISHABLE_KEY / SUPABASE_SECRET_KEY). Edge functions read the platform-injected SUPABASE_* env vars directly — no SB_* mirror. | | db | PATCH PostgREST to expose the api schema. | | auth | PATCH auth config (hooks + signup settings). | | all | Run all three in order. |

Both positionals are optional — omit either (or both) for an interactive picker:

agentlink env config                      # Pick subcommand + env interactively
agentlink env config secrets              # Secrets; env picker
agentlink env config prod                 # Env=prod; subcommand picker
agentlink env config secrets prod         # Both specified
agentlink env config auth prod            # Just auth, against prod (confirms)
agentlink env config all dev --yes        # Full re-apply to dev, no prompts
agentlink env config secrets --env prod   # --env flag accepted for CI scripts

Idempotent. Works on bare projects (no supabase/schemas required). Cloud-only — env config all local is rejected.

agentlink frontend <name>

Scaffold only the frontend template (no Supabase setup).

agentlink frontend my-app           # React + Vite
agentlink frontend my-app --nextjs  # NextJS

agentlink template is the previous name and still works, but prints a deprecation warning.

Typical workflows

First-time scaffold, iterate, deploy to prod

# 1. Scaffold a cloud dev project
agentlink my-app --prompt "build a project tracker"

# 2. Agent builds — you iterate locally, `db apply` runs against dev.

# 3. Connect prod (creates a separate Supabase project)
cd my-app
agentlink env add prod

# 4. Deploy
agentlink env deploy prod        # Prompts y/N; deploys schemas + functions

Agent-driven scaffold, user finishes in terminal

# 1. Agent (no browser access) scaffolds only — no Supabase touched
agentlink my-app --skip-env --prompt "..."

# 2. User, in their terminal:
cd my-app
agentlink env add dev            # OAuth opens browser, env is ready

# 3. Continue with the agent — schemas are ready to apply.
agentlink db apply

Hotfix on prod

# Edit supabase/schemas/*.sql locally
agentlink env deploy prod         # Pushes just the delta + functions

Rebuild migration history early in a project

# Dev DB is messy, migration files are inconsistent
agentlink db rebuild              # Wipes migrations, re-applies schemas, creates one baseline

What it does

The scaffold runs a multi-step process:

1. Prerequisites — Supabase CLI and pgdelta come bundled with agentlink-sh (no manual install). Local mode also checks for psql and Docker.
2. Configure files — Writes template files, config.toml, and .env.local
3. Start Supabase — Starts locally (Docker) or creates a Cloud project
4. Read config — Reads Supabase API keys and connection info
5. Write env — Updates .env.local with API keys and DB URL
6. Setup database — Applies SQL schemas, writes migrations, configures auth
7. Verify setup — Runs verification queries to confirm all components
8. Setup frontend — Writes React + Vite or NextJS files (if selected)
9. Install frontend deps — Runs npm install for the frontend
10. Configure Claude Code — Sets up CLAUDE.md and Claude settings
11. Install MCP — Installs Supabase MCP server (local mode only)
12. Install plugin — Installs Agent Link plugin and companion skills
13. Finalize — Creates git repo, writes agentlink.json manifest

Running agentlink inside an existing project (with agentlink.json) triggers the update flow instead, which patches template files, updates the plugin, applies schema changes, and regenerates migrations.

Modes

Cloud mode (default)

Creates a Supabase Cloud project. No local Docker or psql required. Uses the Management API for database operations, auth config, PostgREST config, and edge function deployment. Authenticates via OAuth (browser), token flag (--token), or cached credentials (~/.config/agentlink/credentials.json). Region is auto-detected from your timezone.

Local mode (--local)

Runs Supabase in Docker via supabase start. Requires Docker and psql. Applies schemas via psql. Installs the Supabase MCP server for Claude Code.

Frontend options

| Option | Frontend | Key features | | ------------------------------ | ------------------ | ------------------------------------------------- | | React + Vite (default) | Vite + React | Auth UI, theme switcher, shadcn/ui components | | NextJS (--nextjs) | Next.js App Router | SSR, server/client Supabase modules, same auth UI | | Backend only (--no-frontend) | None | Minimal package.json with dev dependencies only |

Companion skills

The CLI installs all recommended companion skills for Claude Code automatically. Use --no-skills to skip.

Base skills (all frontends):

• supabase/agent-skills@supabase-postgres-best-practices (required)
• anthropics/skills@frontend-design
• shadcn/ui
• vercel-labs/agent-skills@vercel-react-best-practices
• resend/react-email
• resend/email-best-practices
• resend/resend-skills

Additional for NextJS:

• vercel-labs/next-skills --skill next-best-practices

Scaffolded project structure

my-app/
├── agentlink.json                  # Project manifest
├── CLAUDE.md                       # AI agent instructions
├── .env.local                      # Environment variables
├── .env.example
├── .claude/
│   └── settings.local.json         # Claude Code permissions
├── supabase/
│   ├── config.toml
│   ├── schemas/
│   │   ├── _schemas.sql            # Schema + role grants
│   │   ├── _extensions.sql         # Extension declarations
│   │   ├── public/
│   │   │   ├── profiles.sql        # User profiles table
│   │   │   ├── multitenancy.sql    # Tenants, memberships, invitations
│   │   │   ├── _auth_tenant.sql    # Tenant auth helpers (RLS)
│   │   │   ├── _internal_admin.sql # Vault, edge function calls, set_updated_at
│   │   │   └── _hooks.sql          # Auth hooks
│   │   └── api/
│   │       ├── profile.sql         # Profile RPCs
│   │       └── tenant.sql          # Tenant/invitation/membership RPCs
│   ├── migrations/                 # Generated (never hand-written)
│   └── functions/
│       ├── _shared/
│       │   ├── withSupabase.ts     # Auth wrapper for edge functions
│       │   ├── responses.ts        # Response helpers
│       │   └── types.ts            # Type definitions
│       ├── queue-worker/           # PGMQ message queue handler
│       └── send-email/             # Email sending + templates
├── src/                            # Frontend source (Vite or NextJS)
└── package.json

Development

See DEVELOPMENT.md for the internal dev guide (source file layout, template system, adding scaffolded files).