Skip to main content
Use this page to confirm paths and setup output after install. Command examples show supaschema as CLI syntax. In a project install, run it through the local runner from Installation. After installing the package, run init through the local runner for your package manager:

​
Path selection

Install scans the repository before writing config:
  • one detected schema folder and one detected migrations folder are used automatically;
  • provider markers seed default folders when no existing folders are found;
  • Supabase projects use Supabase CLI sync targets by default;
  • non-Supabase projects reuse existing database URL environment variable names from .env* files when present;
  • generic PostgreSQL projects use database/schemas and database/migrations;
  • multiple candidates that still need confirmation are recorded in .supaschema/install.json with agentInstructions;
  • interactive terminals can confirm paths immediately.
Do not run the first diff from a guessed path. If .supaschema/install.json says pathConfirmationNeeded: true, follow its agentInstructions; config validate, doctor, and zero-source diff block until supaschema.config.json explicitly sets schemaPaths and migrationsDir.
Supabase projects with _bootstrap inventory or an owner brief marking supabase/schemas/** as non-generator inventory still get supaschema.config.json. Those installs set schema diff and migration sync to manual workflow policy so setup is usable immediately without enabling automatic schema-write migration generation. Supabase managed schemas are also seeded into schemas.exclude, and _bootstrap directories are skipped by schema-source readers because role/control-plane bootstrap SQL is not generated migration input. Commit supaschema.config.json after confirming paths. It keeps humans, CI, and coding agents on the same schema tree and migration directory. Resolved installs do not create .supaschema/ or supaschema-only credential files; supaschema.config.json is the durable project state.

​
Agent addendum

Default install writes package-owned .agents, .claude, and .codex enforcement files when they are missing and merges the matching hook registration for the detected package manager. It preserves existing non-identical files, reports skipped non-mergeable hook config for agent repair, and does not write AGENTS.md or CLAUDE.md. If an existing project already uses AGENTS.md or CLAUDE.md, keep those files as consumer-owned root briefs and point them at the installed .agents/prompts/supaschema-install.md only when the project wants that routing.

​
Check setup

Run doctor when setup behaves unexpectedly:
doctor checks Node, parser load, config validity, database URL resolution, optional database reachability, CREATEDB, migration history, and declarative schema paths.

​
Configuration

Config file

Review paths, migrations, type outputs, validators, and planner policies.

Environments

Configure named targets and database URL resolution.

Hints

Approve reviewed destructive changes and renames.
Last modified on July 10, 2026