Cli

CLI

The agentlink-sh CLI scaffolds new Supabase projects and updates existing ones. It handles infrastructure setup, template files, database configuration, and migration generation.

> Running the CLI (since 1.4): prefer the project-local install. Projects scaffolded with 1.4+ pin agentlink-sh as a devDependency, so the project carries its own CLI version — reproducible, and it never auto-jumps across a breaking major. Note the names differ: the package is agentlink-sh, the installed binary is agentlink (no -sh). For in-project commands (check, db apply, db migrate, env deploy, --force-update, …): > - Use pnpm exec agentlink when the dep is present (check with pnpm exec agentlink --version, or look for agentlink-sh in package.json). > - If it's missing (a pre-1.4 project): add it with pnpm add -D agentlink-sh, or run --force-update once (it backfills the declaration), then pnpm install. > - Don't use bare npx agentlink — with no local install it resolves a different npm package, not ours. Use pnpm exec agentlink (local) or npx agentlink-sh@latest (one-shot). > - Only create uses @latest — a brand-new project has no local CLI yet: npx agentlink-sh@latest . > > The command docs below still write npx agentlink-sh@latest for brevity; when a local install exists, pnpm exec agentlink is the equivalent and preferred form.

> Workflow playbook: see references/workflows.md for common user scenarios — "start a new project from zero," "add a prod env," "deploy to prod," "recover from a failed deploy," etc. Each entry lists what questions to ask the user and which commands to run.

---

Prerequisites

AgentLink does NOT install its own tooling, and it does NOT require an AI coding agent (Claude Code or Cursor) to be on PATH in order to scaffold — it writes the project files and the editor config regardless, then you open the project in whichever agent you chose. It validates the tooling it needs and points users at the setup script at https://agentlink.sh/start if anything is missing; it never tries to curl | bash anything itself. This is intentional — mixing tooling installation into scaffold meant every platform-specific install failure surfaced mid-scaffold with no context.

Check these BEFORE attempting to scaffold — every command runs through npx, so a missing prerequisite makes the CLI fail or hang, and the agent must NOT fall back to hand-creating files:

| Requirement | When | Verify | If missing | |---|---|---|---| | Node.js 18+ (node / npx) | Always — the entire CLI is npx agentlink-sh@latest | node --version | Stop and tell the user to install Node (the npx call otherwise times out — this is a common silent failure). Don't proceed. | | Supabase CLI | Always | supabase --version | Point at https://agentlink.sh/start. | | Docker + psql | Local dev (--local) | docker info, psql --version | Required only for the local path; cloud-only scaffolds don't need them. | | Supabase account | Cloud dev / prod (env add dev/prod) | — (browser OAuth at env add) | The user must own the OAuth + project creation; the agent can't browse. | | Resend account | Transactional email (auth emails, product email) | — | Configured per-env: resend setup --env --api-key … --email …. Not needed to scaffold. See [Resend setup](./references/resend.md). |

> ⚠️ If node/npx is absent, the scaffold command times out with no useful output. That is NOT a signal to build the project by hand — it's a missing-Node signal. Surface it to the user, get Node installed, then run the CLI.

---

Commands

Scaffold a new project

> 🛑 Before you scaffold, ASK the user where the dev environment should live: local Docker or Supabase Cloud. This decision picks the command — don't default silently to --skip-env. > - Cloud → needs browser OAuth (which the agent doesn't have) → scaffold files only with --skip-env, then hand off env add dev. > - Local → no browser needed → the agent runs it end-to-end with --local (requires Docker + psql). > > --skip-env is the canonical path only after the user has chosen cloud. It is not a blanket agent default — running it without asking silently forces the cloud path on a user who may have wanted local. See workflow #1 in references/workflows.md.

npx agentlink-sh@latest        # interactive — handles login + project creation
npx agentlink-sh@latest .            # scaffold in current directory

Creates template files, config, schema files, frontend (React + TanStack Start, SPA mode), configures your chosen agent editor (Claude Code and/or Cursor), and installs the companion skills (plus the plugin in Claude Code). Cloud is the default — the wizard prompts for Supabase OAuth (browser), org selection, and region. The wizard also asks which agent editor(s) to set up.

Scaffold without env creation (--skip-env)

npx agentlink-sh@latest  --skip-env

This is the canonical path for agent-driven scaffolding when the user chose CLOUD dev (ask first — see the scaffold-decision callout above; for local dev use --local and run it end-to-end). Writes all files, installs frontend + backend deps, configures the chosen agent editor (Claude Code and/or Cursor), installs the companion skills (plus the plugin in Claude Code) — but skips every Supabase-touching step: no OAuth (needs a browser), no project creation, no local Docker, no .env.local credentials, no edge-function deploy.

After scaffold completes, the user finishes setup by running this in a terminal:

pnpm exec agentlink env add dev

That step does the browser OAuth, creates/links the cloud project, provisions schema + edge functions, and populates .env.local. The scaffolded AGENTS.md surfaces this as a prominent "▶ Next step" callout at the top.

Mutually exclusive with --local and --link — all three imply different intents about env creation, so the CLI errors out if combined. Use --skip-env specifically for agent-driven flows; use --link when you already have credentials; use --local when the user wants a local Docker env now.

Scaffold with --link (non-interactive)

npx agentlink-sh@latest  --link \
  --project-ref  \
  --db-url "" \
  --api-url "" \
  --publishable-key "" \
  --secret-key ""

Scaffolds files + connects to an existing Supabase project + applies the full SQL setup in one step. No interactive prompts, no supabase login. Use when connection details are already known (e.g., from the Supabase connector MCP). Not compatible with --skip-env — --link creates an env now, --skip-env defers it.

Scaffold in an existing project

cd my-project && npx agentlink-sh@latest .

Detects the existing directory and integrates AgentLink into it. Requires a clean git working tree.

Bare mode — env management without the full scaffold

For users who want Supabase env plumbing (OAuth, project create/select, .env.local wiring) but NOT the AgentLink scaffold (schemas, RLS helpers, RPC layout, skills), running env add in a non-scaffolded directory opts into bare mode:

cd my-existing-app
pnpm exec agentlink env add dev
# → "No agentlink.json found" menu with three choices:
#     - Run the full AgentLink scaffold (recommended) → exits, tells user to run `npx agentlink-sh@latest`
#     - Continue without full features → writes a minimal agentlink.json, runs the Supabase flow
#     - Cancel

If the user picks "Continue without full features," the CLI writes a minimal agentlink.json with bare: true and runs the full Supabase flow (OAuth → org pick → project create/select → credentials → .env.local). No schemas applied, no server-side config (vault / PostgREST / auth hooks), no AGENTS.md touched — the user's file is theirs. env use / env add all skip writeAgentsMd in bare mode.

What works in bare mode: env add/use/remove/list, env config [secrets|db|auth|all], db password, db url. What's a no-op until the user adds content: db apply (skips with "supabase/database/ not found"), env deploy (picks up migrations/schemas/functions incrementally as they appear).

Upgrade path: pnpm exec agentlink --force-update converts a bare project to the full scaffold.

Update an existing project

pnpm exec agentlink --force-update

Re-applies template files, patches config.toml, runs SQL setup, and regenerates migrations if schemas changed. Use after a CLI version upgrade or when check reports missing components.

Diagnose

pnpm exec agentlink check            # Check default environment
pnpm exec agentlink check --env dev  # Check specific environment

Outputs JSON with ready, supabase_running, database (extensions, queues, functions, secrets, api_schema), and files. Read-only — reports problems but does not fix them.

Component info

pnpm exec agentlink info          # Summary list
pnpm exec agentlink info    # Detail for one component

Shows type, summary, description, signature, and related components. Use to understand what a missing component does.

Flags

| Flag | Effect | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --no-skills | Skip companion skill installation | | --no-frontend | Skip frontend scaffolding (backend only) | | -y, --yes | Auto-confirm all prompts | | --local | Use local Docker instead of Supabase Cloud (cloud is default) | | --skip-env | Scaffold files only — skip all Supabase setup (OAuth, project creation, Docker). User runs pnpm exec agentlink env add dev after. Use for agent-driven scaffolding. Mutually exclusive with --local / --link. | | --force-update | Force update even if project is up to date | | --link | Non-interactive scaffold + link (requires --project-ref, --db-url, --api-url, --publishable-key, --secret-key). Mutually exclusive with --skip-env. | | --project-ref | Supabase project reference ID (used with --link) | | --db-url | Database connection URL (used with --link) | | --api-url | Supabase API URL (used with --link) | | --publishable-key | Supabase publishable/anon key (used with --link) | | --secret-key | Supabase secret/service role key (used with --link) | | --prompt | What to build (passed to Claude Code on launch) | | --resume | Resume a previously failed scaffold | | --non-interactive | Error instead of prompting when info is missing | | --debug | Write detailed log to agentlink-debug.log |

---

Database Operations

Apply schemas

pnpm exec agentlink db apply                    # Auto-detects DB from .env.local
pnpm exec agentlink db apply --env dev          # Target specific environment
pnpm exec agentlink db apply --db-url "postgresql://..."  # Explicit DB URL

Pushes your schema-file changes to the live DB — no Docker needed. It handles changes to existing objects, so editing a table/column (an ALTER) lands without a rebuild. --legacy falls back to a create-only mode; --allow-destructive is required only for row-data-loss ops (DROP TABLE/COLUMN/SCHEMA, TRUNCATE). db apply also applies the imperative resources (storage/, cron/, rbac/).

Apply imperative resources only

pnpm exec agentlink db resources                 # storage/ + cron/ + rbac/, nothing else
pnpm exec agentlink db resources --env dev

Applies only the imperative folders (supabase/database/ storage/, cron/, rbac/) — no schema diff, no type-gen. Use it after editing a cron job, storage bucket, or RBAC file when you don't want a full db apply. Idempotent. (db rbac-sync is the rbac-only subset.)

Run SQL

pnpm exec agentlink db sql "SELECT * FROM public.profiles LIMIT 5"
pnpm exec agentlink db sql "SELECT 1" --env dev
pnpm exec agentlink db sql "SELECT 1" --json    # JSON output (cloud only)

Generate types

pnpm exec agentlink db types                    # Auto-detects output path
pnpm exec agentlink db types --env dev          # From specific environment
pnpm exec agentlink db types --output types/db.ts  # Custom output path

Generate migration

pnpm exec agentlink db migrate add_charts       # From default DB
pnpm exec agentlink db migrate add_charts --env dev

Set database password

pnpm exec agentlink db password                  # Interactive: shows dashboard reset link + prompts
pnpm exec agentlink db password "newpassword"    # Non-interactive: sets directly

Shows or sets the database password for the active cloud project. The password is stored in ~/.config/agentlink/credentials.json (per project ref). Use when the DB password was reset in the S

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomaspozo
• Source: tomaspozo/agentlink
• License: MIT
• Homepage: https://agentlink.sh

Install and usage instructions live in the source repository linked above.