# Cli > AgentLink CLI usage — project scaffolding, updates/upgrades, migration management, environments, deploy-to-prod, backups, and credentials. Use when the task involves running `agentlink-sh` / `agentlink` commands, managing migrations, managing environments (link, secrets, `env deploy` to prod), running or restoring backups, handling project credentials/keys, troubleshooting db apply / db migrate i… - **Type:** Skill - **Install:** `agentstack add skill-tomaspozo-agentlink-cli` - **Verified:** Pending review - **Seller:** [tomaspozo](https://agentstack.voostack.com/s/tomaspozo) - **Installs:** 0 - **Category:** [Security](https://agentstack.voostack.com/c/security) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tomaspozo](https://github.com/tomaspozo) - **Source:** https://github.com/tomaspozo/agentlink/tree/main/skills/cli - **Website:** https://agentlink.sh ## Install ```sh agentstack add skill-tomaspozo-agentlink-cli ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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`. ```bash 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`) ```bash 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: ```bash 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) ```bash 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 ```bash 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**: ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash pnpm exec agentlink db migrate add_charts # From default DB pnpm exec agentlink db migrate add_charts --env dev ``` ### Set database password ```bash 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](https://github.com/tomaspozo) - **Source:** [tomaspozo/agentlink](https://github.com/tomaspozo/agentlink) - **License:** MIT - **Homepage:** https://agentlink.sh Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-tomaspozo-agentlink-cli - Seller: https://agentstack.voostack.com/s/tomaspozo - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.