CLI

The potalab base CLI covers migrations, type generation, RLS tests and linting. It needs Node 22 or later.

Global options: --json (one JSON document on stdout, progress on stderr), -q, --quiet, --workdir <dir>. The project root is the nearest parent directory that contains potalab/config.toml.

Project and migrations

Command	What it does
potalab base init [--project-id id]	Creates potalab/ (config.toml, migrations/, seed.sql, an example RLS test). Never overwrites an existing file.
potalab base link --project-ref r | --db-url u [--api-url a]	Links the folder to a project. The database password is never stored: pass it with POTALAB_BASE_DB_PASSWORD or PGPASSWORD.
potalab base migration new <name>	Creates potalab/migrations/<YYYYMMDDHHMMSS>_<name>.sql (UTC).
potalab base migration list	Shows the apply order.
potalab base db push [--db-url u] [--dry-run] [--include-all]	Applies pending migrations, one transaction each, tracked in base.schema_migrations. Refuses migrations older than the newest applied one unless --include-all, and warns about edited or missing ones.
potalab base db pull [--db-url u] [--name n] [--no-record]	Dumps the schema of the exposed schemas as a baseline migration. There is no schema diff yet.

Migration files must not contain BEGIN or COMMIT (each file already runs in one transaction), and CREATE INDEX CONCURRENTLY is not allowed.

Note

Remote db push and db pull need --db-url with the project owner’s connection. The Management API transport (--project-ref only) is not implemented and exits with code 6. Migrations applied through the dashboard or the Management API are tracked separately from db push, so choose one path per project.

Types, tests and lint

Command	What it does
potalab base gen types [--db-url u] [--schema s ...] [-o file]	Prints the Database interface used by createClient<Database>(). The output is identical for the same schema.
potalab base lint [--db-url u] [--schema s ...] [--level info|warn|error] [--fail-on error|warn|info|none] [--json]	Runs the security and performance advisor, with the same rules as the dashboard Advisors page. Exits 1 on a finding at or above --fail-on (default error).
potalab base test db [files...]	Runs pgTAP tests from potalab/tests against the local development database.

gen types marks nullable columns | null, makes columns with defaults optional on insert, types identity ALWAYS and generated columns as never, and maps SETOF <table> functions to that table’s rows.

Inside pgTAP tests (use begin ... rollback), these helpers switch role and claims like a real request:

select tests.authenticate_as('11111111-1111-1111-1111-111111111111', '{"app_role":"admin"}');
select tests.authenticate_as_anon();
select tests.authenticate_as_service_role();
select tests.clear_authentication();

Local development

potalab base start, stop, status and db reset run a local development stack. It needs Docker and has gaps compared to the hosted platform (for example no dashboard, Management API, webhooks, realtime or storage API), so prefer testing against a development project.

CI example

- run: potalab base lint --db-url "$DATABASE_URL" --fail-on warn
- run: potalab base gen types --db-url "$DATABASE_URL" -o src/database.types.ts && git diff --exit-code src/database.types.ts

Exit codes

Code	Meaning
0	ok
1	unexpected error, or lint findings at or above --fail-on
2	usage error, invalid config, or project not initialized
3	Docker missing, or the local stack is not running
4	database error (connect, migration, seed)
5	pgTAP tests failed
6	not implemented

Errors print error: ... and a hint: ...; with --json they print {"error":{code,message,hint}}.