agentlink

Teach AI agents the right way to build on Supabase.

Agent Link is an opinionated skill set for AI coding agents — it works in both Claude Code and Cursor — 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 + TanStack Start, an SPA on Vite) 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, six 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.

Run

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

npx agentlink-sh@latest

npx always pulls the latest version. There's no global install step — every command below is prefixed with npx agentlink-sh@latest.

Prerequisites

The CLI does not install tooling for you — have these in place first:

| Tool / account | When you need it | Notes | |---|---|---| | Node.js 18+ (node / npx) | Always — every command is npx agentlink-sh@latest | Without it the npx call fails or times out. Install from nodejs.org or a version manager. | | Supabase CLI | Always | Bundled checks point at agentlink.sh/start if missing. | | Docker + psql | Local development (--local) | The Docker stack runs Supabase locally; psql applies SQL against it. Not needed for cloud-only. | | Supabase account | Cloud development & production | For env add dev / env add prod — browser OAuth, project creation, deploys. | | Resend account | Transactional email | For auth emails (invites, password resets) and product email via edge functions. Add the API key when you wire email. |

Full setup script: agentlink.sh/start.

Quick start

# Create a new project (cloud by default)
npx agentlink-sh@latest my-app

# With a prompt for your agent
npx agentlink-sh@latest my-app --prompt "Build a project management tool with kanban boards"

# Choose which agent editor(s) to configure: cursor, claude-code, or both
npx agentlink-sh@latest my-app --editor both

# Interactive wizard
npx agentlink-sh@latest

Commands

npx agentlink-sh@latest [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
npx agentlink-sh@latest

# With project name
npx agentlink-sh@latest my-app

# With prompt (passed to your agent on launch)
npx agentlink-sh@latest my-app --prompt "Build a project management tool"

# Local Docker mode (instead of cloud)
npx agentlink-sh@latest my-app --local

# Backend only (no frontend)
npx agentlink-sh@latest my-app --no-frontend

# Skip companion skills
npx agentlink-sh@latest 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.
npx agentlink-sh@latest my-app --skip-env

# Non-interactive (CI-friendly)
npx agentlink-sh@latest 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) | | --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) |

npx agentlink-sh@latest sb login

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

npx agentlink-sh@latest sb login

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

npx agentlink-sh@latest sb token

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

npx agentlink-sh@latest sb token show           # Print the current token and its source
npx agentlink-sh@latest sb token set sbp_...    # Save a new token

npx agentlink-sh@latest 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.

npx agentlink-sh@latest env add              # Interactive picker
npx agentlink-sh@latest env add dev          # Connect the dev cloud environment
npx agentlink-sh@latest env add prod         # Connect production. Does NOT touch .env.local.
npx agentlink-sh@latest env add dev --no-deploy    # Register the env but skip the initial deploy
npx agentlink-sh@latest 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 `npx agentlink-sh@latest 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.

npx agentlink-sh@latest env use              # Interactive picker
npx agentlink-sh@latest env use dev          # Switch to dev
npx agentlink-sh@latest env use local        # Switch to local Docker
npx agentlink-sh@latest 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.

npx agentlink-sh@latest env deploy              # Interactive picker (preselects cloud.default)
npx agentlink-sh@latest env deploy dev          # Deploy to dev
npx agentlink-sh@latest env deploy prod         # Deploy to prod (requires y/N confirmation)
npx agentlink-sh@latest env deploy prod --yes   # Skip the confirmation (for CI)
npx agentlink-sh@latest 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.

npx agentlink-sh@latest env list

env remove <name>

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

npx agentlink-sh@latest env remove prod
npx agentlink-sh@latest env remove prod -y   # Skip confirmations

The top-level deploy command has been removed entirely; use env deploy instead. Transferring a Supabase project to a new org is handled automatically — env deploy / env config detect the move and update agentlink.json; or run env add <name> → Relink to a different Supabase project, which detects the same project and offers to keep the password on file (--keep-password for CI).

npx agentlink-sh@latest check

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

npx agentlink-sh@latest check
npx agentlink-sh@latest check --env prod    # Check a specific cloud env

npx agentlink-sh@latest info [name]

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

npx agentlink-sh@latest info                # List all components
npx agentlink-sh@latest info tenant_select  # Detail for one component

npx agentlink-sh@latest 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/database/schemas/ to the database using pgdelta declarative apply. Generates TypeScript types afterwards unless --skip-types is set.

npx agentlink-sh@latest db apply
npx agentlink-sh@latest db apply --skip-types
npx agentlink-sh@latest db apply --env prod
npx agentlink-sh@latest 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.

npx agentlink-sh@latest db migrate add_charts_table
npx agentlink-sh@latest 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.

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

db types

Regenerate src/types/database.ts from the api schema.

npx agentlink-sh@latest db types
npx agentlink-sh@latest 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.

npx agentlink-sh@latest 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.

npx agentlink-sh@latest db url
npx agentlink-sh@latest db url --fix

db password [value]

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

npx agentlink-sh@latest db password                 # Prompt (masked) + save
npx agentlink-sh@latest 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.

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

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

npx agentlink-sh@latest 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:

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

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

npx agentlink-sh@latest frontend <name>

Scaffold only the frontend template (no Supabase setup).

npx agentlink-sh@latest frontend my-app           # React + TanStack Start (SPA, Vite-based)

frontend replaces the previous template command, which still works but prints a deprecation warning.

Typical workflows

First-time scaffold, iterate, deploy to prod

# 1. Scaffold a cloud dev project
npx agentlink-sh@latest 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
npx agentlink-sh@latest env add prod

# 4. Deploy
npx agentlink-sh@latest 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
npx agentlink-sh@latest my-app --skip-env --prompt "..."

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

# 3. Continue with the agent — schemas are ready to apply.
npx agentlink-sh@latest db apply

Hotfix on prod

# Edit supabase/database/schemas/**/*.sql locally
npx agentlink-sh@latest env deploy prod         # Pushes just the delta + functions

Rebuild migration history early in a project

# Dev DB is messy, migration files are inconsistent
npx agentlink-sh@latest 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 the React + TanStack Start (SPA, Vite-based) files (unless --no-frontend)
9. Install frontend deps — Runs npm install for the frontend
10. Configure agent editor — Sets up AGENTS.md, and (for Claude Code) .claude/settings.local.json
11. Install MCP — Writes the Supabase MCP config — .mcp.json (Claude Code) and/or .cursor/mcp.json (Cursor), local mode only
12. Install skills — Installs the companion skills for the chosen editor(s). Claude Code also auto-registers the plugin from settings on first launch; in Cursor, run /add-plugin tomaspozo/agentlink
13. Finalize — Creates git repo, writes agentlink.json manifest

Running npx agentlink-sh@latest 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. Writes the Supabase MCP config for the chosen agent editor(s).

Frontend options

| Option | Frontend | Key features | | ------------------------------ | ----------------------------------- | ------------------------------------------------- | | Default | React + TanStack Start (SPA, Vite) | Auth UI, theme switcher, shadcn/ui components | | Backend only (--no-frontend) | None | Minimal package.json with dev dependencies only |

Companion skills

The CLI installs all recommended companion skills for the chosen agent editor(s) — Cursor, Claude Code, or both — automatically. Use --no-skills to skip.

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

Scaffolded project structure

my-app/
├── agentlink.json                  # Project manifest
├── AGENTS.md                       # AI agent instructions
├── .env.local                      # Environment variables
├── .env.example
├── .claude/
│   └── settings.local.json         # Claude Code permissions
├── supabase/
│   ├── config.toml
│   ├── database/                   # One object per file (pgdelta layout)
│   │   ├── cluster/
│   │   │   └── extensions/         # One file per extension: pgmq.sql, pg_cron.sql, …
│   │   ├── rbac/                   # RBAC reference data (reconciled, not migrated)
│   │   │   ├── roles.sql
│   │   │   ├── permissions.sql
│   │   │   └── role_permissions.sql
│   │   └── schemas/
│   │       ├── public/
│   │       │   ├── schema.sql       # Schema creation + role grants
│   │       │   ├── tables/          # profiles.sql, tenants.sql, memberships.sql,
│   │       │   │                    #   invitations.sql, roles.sql, permissions.sql, …
│   │       │   └── functions/       # _internal_admin_*.sql, _auth_*.sql, _hook_*.sql,
│   │       │                        #   auth_has_access.sql, set_updated_at.sql, …
│   │       └── api/
│   │           ├── schema.sql
│   │           ├── tables/          # agentlink_tasks.sql, …
│   │           └── functions/       # profile_get.sql, tenant_create.sql,
│   │                                #   invitation_create.sql, _admin_queue_read.sql, …
│   ├── migrations/                 # Generated (never hand-written)
│   └── functions/
│       ├── _shared/
│       │   ├── responses.ts         # Response helpers
│       │   └── email-components/    # Shared React Email components
│       ├── internal-queue-worker/   # secret: PGMQ message queue handler
│       ├── internal-send-auth-email/# secret: auth emails
│       └── internal-invite-member/  # secret: invitation emails
├── src/                            # Frontend source (React + TanStack Start)
└── package.json

withSupabase is imported from the @supabase/server npm package — there is no local _shared/withSupabase.ts.

Telemetry

AgentLink collects anonymous usage data to understand which commands are used and where setup flows break down, so we can improve the tool. It's on by default, and you'll see a one-time notice on first run.

What we collect: which command ran, success/failure and duration, scaffold funnel steps, and coarse context — CLI version, OS/arch, Node version, whether the run is an AI agent / CI / human, and the project mode (local/cloud). Each install has a random anonymous ID.

What we never collect: your --prompt text, project names, file paths, source code, tokens, database URLs, or any option values — only the names of the flags you passed.

Opt out anytime:

npx agentlink-sh@latest telemetry off     # persistent opt-out
npx agentlink-sh@latest telemetry status  # check current state

Telemetry also respects the DO_NOT_TRACK standard and AGENTLINK_TELEMETRY=0:

DO_NOT_TRACK=1 npx agentlink-sh@latest ...

It is best-effort and fully sandboxed: telemetry never slows down, blocks, or breaks a command, and any network failure is silent.

Development

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