> ## Documentation Index > Fetch the complete documentation index at: https://supaschema.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Installation > Install supaschema in a PostgreSQL project and give coding agents the correct setup prompt. Use this page to add supaschema to a project. Install from the package or workspace that owns your schema workflow, not from a clone of the supaschema source repository. Use the project's package manager; do not create a second lockfile. For npm, the complete zero-config setup is a durable project install followed by local initialization: ```bash theme={null} npm install supaschema npm exec -- supaschema init ``` Package installation downloads the CLI, config schema, and agent bundle. `init` then detects the consuming project and installs or merges the active config, directories, scripts, and AI-agent surfaces. It is safe to rerun after upgrades. | Manager | Install command | Setup command | Run command | | ------- | ------------------------ | ------------------------------------- | -------------------------------------- | | npm | `npm install supaschema` | `npm exec -- supaschema init` | `npm exec -- supaschema ` | | pnpm | `pnpm add supaschema` | `pnpm exec supaschema init` | `pnpm exec supaschema ` | | Yarn | `yarn add supaschema` | `yarn exec supaschema init` | `yarn exec supaschema ` | | Bun | `bun add supaschema` | `./node_modules/.bin/supaschema init` | `./node_modules/.bin/supaschema ` | supaschema is a runtime project dependency because the CLI, config schema, generated-output workflow, and coding-agent enforcement bundle are part of the consuming repo's migration workflow. For workspaces, run both install and setup from the package directory that owns `supaschema.config.json` and the schema files. Dependency-targeting flags such as npm `--workspace`, pnpm `--filter`, or Yarn `workspace` can update the member manifest while setup still runs from the command's current directory. Use root-level workspace flags only when the workspace root owns the schema workflow. For pnpm, `pnpm add supaschema` adds the dependency to the package in the current directory. Run `pnpm add -w supaschema` only when the workspace root owns the schema workflow. pnpm v11 defaults `minimumReleaseAge` to one day; keep that supply-chain protection for normal installs. Use `--config.minimumReleaseAge=0` only when troubleshooting an immediate install of a just-published supaschema version. Stop before installing if package-manager signals conflict, the workspace owner is unclear, or Node is below 22.12. ## Agent install prompt Use this prompt when asking an AI coding agent to install supaschema. Install supaschema in this project. Work from the project root, not from a nested clone of the supaschema source repository. First identify the package manager from `packageManager`, `devEngines.packageManager`, lockfiles, and workspace files. Use that manager from the package directory that owns the schema workflow; do not run npm in a pnpm, Yarn, or Bun project, and do not create a second lockfile. Use the matching local runner for every command after install: * npm: `npm exec -- supaschema ` * pnpm: `pnpm exec supaschema ` * Yarn: `yarn exec supaschema ` * Bun: `./node_modules/.bin/supaschema ` After install, run ` init`. It uses the consuming repo's package manager, workspace owner, provider markers, schema paths, and migration paths to create config, directories, scripts, and active AI-agent enforcement. It installs missing package-owned `.agents`, `.claude`, and `.codex` files, merges `.claude/settings.json` and `.codex/hooks.json`, preserves existing non-identical files, reports skipped non-mergeable hook config, and does not write `AGENTS.md` or `CLAUDE.md`. If `.supaschema/install.json` exists, inspect it first; when it has `pathConfirmationNeeded: true`, follow `agentInstructions`, choose the owning paths from the detected candidates, and write those paths into `supaschema.config.json`. If no pending install manifest exists, inspect `supaschema.config.json`. Then run: ` --version` ` config validate --json` Default `supaschema init` installs only focused non-apply scripts: `supaschema:diff`, `supaschema:stage`, `supaschema:types`, and `supaschema:check`. Use direct CLI commands for setup diagnostics, full sync/apply, and database execution verification: ` config validate --json`, ` sync`, ` apply`, and ` verify`. Report the configured schema paths, migration directory, generated TypeScript/Zod outputs, whether path confirmation is still pending, and whether the agent-bundle install completed or reported skipped files to repair from `node_modules/supaschema/agent-bundle/INSTALL.md`. Supabase inventory or `_bootstrap` projects should have config present with manual schema diff and migration sync policy, managed schemas in `schemas.exclude`, and no pending install state. Re-run `supaschema init` after package upgrades to persist config-contract repairs. Do not apply migrations to any database unless I explicitly ask for that or the configured apply policy allows it: `workflow.migration_sync` must permit apply, exactly one `sync.targets..mode` must select the target, verify must pass, and any remote approval variable must be set by the operator. For schema changes, edit the declarative schema tree, run ` sync`, and treat generated migrations as build output. ## Verify ```bash theme={null} --version config validate ``` Run setup explicitly through the matching local runner after install. It is idempotent, so it is safe to rerun when config or directories need repair: ```bash theme={null} init ``` ## Database URLs Database URLs are only needed for commands that inspect, compare, or directly sync a live database. `init` does not write credential values. Supabase projects use the configured Supabase CLI runner. Other PostgreSQL projects reuse existing database URL variable names from `.env*` files in `sync.targets` when present. ```bash theme={null} SUPASCHEMA_DATABASE_URL="postgres://..." diff ``` Use named environments only when you need an additional named target. Do not create a second credential variable just for supaschema when an application database URL variable already exists. A database URL does not authorize an apply. supaschema keeps apply fail-closed until `workflow.migration_sync` permits it, exactly one configured sync target selects apply mode, verification succeeds, and any remote approval variable is present. Without that explicit policy, `sync` remains a dry run. ## Next steps Confirm detected paths, install output, and environment checks. Generate and check one migration. Review the installed agent enforcement bundle. Review persistent paths, sources, workflow, and environments.