Skip to main content
Use contracts when one repository publishes the database shape another repository consumes. The local commands export and diff JSON contracts without a hosted service. Push and pull use a hosted contract registry only when an operator deployment exists.

​
Run it

npx supaschema contracts export --out schema-contract.json
npx supaschema contracts diff --from schema-contract.json
npx supaschema contracts push --registry-url https://license.example --repo acme/app
npx supaschema contracts pull --registry-url https://license.example --repo acme/app --out schema-contract.json

​
Subcommands

​
export
command
Build a JSON schema contract from --from, defaulting to the configured schema tree.
​
diff
command
Compare --from <file> with --to <source>, defaulting --to to the configured schema tree.
​
push
command
Export --from and store the contract in the hosted registry at /contracts?repo=&name=.
​
pull
command
Retrieve a stored contract from the hosted registry.

​
Flags

​
--from
source
Schema source used by export and push.
​
--to
source
Candidate source used by diff. Defaults to the configured schema tree.
​
--out
file | stdout
Output destination for export and pull. Defaults to stdout.
​
--registry-url
URL
Base URL for the hosted contract registry.
​
--repo
owner/repo
Repository identity bound to the license token.
​
--name
string
Contract name in the registry. Defaults to main.
​
--license-env
environment variable name
Environment variable containing the repo-bound license token. Defaults to SUPASCHEMA_LICENSE.

​
Boundaries

The registry stores schema metadata only after an authenticated client submits it. It does not receive database URLs, migrations, table rows, or live database credentials through the normal routes. Do not pass license tokens in argv. Put the token in the environment variable named by --license-env.

​
Exit codes

CodeMeaning
0Contract command completed.
2diff found error-severity drift diagnostics.
Last modified on June 18, 2026