05 · Real data with Supabase

In the Supabase dashboard, create a new project (the free plan is enough). It's your database — fayz db apply only writes the target shape into it. You'll need four values from it:

• Project URL and anon key — under Project Settings → API. These live in the browser (public).
• Project ref — under Project Settings → General. It's the project identifier.
• Personal access token (PAT) — under Account → Access Tokens. This is a machine secret; it never goes to the browser or into Git.

The scaffold ships a .env.example. Copy it to .env.local (already in .gitignore) and fill it in:

cp .env.example .env.local

# Runtime (go to the browser — public values only)
VITE_SUPABASE_URL=https://YOUR-REF.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

# Tooling (used by `fayz db apply` — do NOT go to the browser)
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_PAT=your-personal-access-token

Before touching the database, look at the plan. --dry-run makes no network calls and doesn't read your PAT — it's always safe to run:

npx @fayz-ai/cli db apply --dry-run

Real output on a freshly created app:

▸ Migration plan for my-store

   1. [spine    ] @fayz-ai/db  — no files

  Notes:
    ⚠ installed @fayz-ai/db ships no migrations/ — the spine step is empty (upgrade to @fayz-ai/db >= 0.1.3 once published)
    ⚠ plugin 'dashboard': @fayz-ai/plugin-dashboard ships no src/migrations — skipped

  Summary: 1 step(s), 0 sql file(s). (dry-run — nothing was applied)

The plan's order is always the same: the core first, then each plugin's versioned migrations, and finally your incubator plugins. In the current CLI output this shows up with the labels spine → drizzle → seed → plugins → incubator (the first three are the core — the label moves to core in the industry pools wave). A step only appears if the corresponding package ships SQL files. With the current package versions the plan is still lean; as plugins start shipping migrations, new steps will show up here.

Once the plan looks the way you want, apply it. This is the command that runs with your credentials (the SUPABASE_PROJECT_REF and SUPABASE_PAT from .env.local) and writes to the database via the Supabase Management API:

npx @fayz-ai/cli db apply

It asks for confirmation before applying (use --yes to skip the prompt in CI). Without both variables set, it stops with a clear error — deliberately, so it never applies against the wrong project.

With the schema in place, change the backend in app.manifest.json from mock to supabase and give it the ref:

{
  "backend": {
    "provider": "supabase",
    "projectRef": "your-project-ref"
  }
}

Then validate everything with doctor:

npx @fayz-ai/cli doctor