CLI commands

The CLI ships as schemic, with sc as a short alias. Run any command with npx schemic <command>. Commands that talk to a database accept the global connection flags and read defaults from schemic.config.ts.

Setup

schemic init

Scaffold the database/ layout, a config file, a sample schema, and an empty migration snapshot. Never overwrites existing files.

$ schemic init

FLAG TYPE DESCRIPTION

schemic doctor

Print the resolved configuration and test the database connection.

$ schemic doctor

FLAG TYPE DESCRIPTION

Migrations

schemic gen [name]

Diff the schema against the snapshot and write a migration for the difference. Writes nothing when there are no changes.

$ schemic gen add_user_role

FLAG TYPE DESCRIPTION

-y boolean Skip the confirmation prompt.

--baseline boolean Regenerate the whole schema from an empty snapshot as one migration.

--force boolean With --baseline, replace existing migrations with the fresh baseline.

schemic migrate [count]

Apply pending migrations in order — all, the next N, or up to a tag. Alias: up.

$ schemic migrate --to 20260613090000_add_role

FLAG TYPE DESCRIPTION

--to <tag> string Apply up to and including this migration.

schemic rollback [count]

Revert applied migrations newest-first. Alias: down.

$ schemic rollback 2

FLAG TYPE DESCRIPTION

--to <tag> string Revert everything applied after this tag.

schemic status

Show applied vs pending migrations, flagging files that changed after apply or are missing.

$ schemic status --json

FLAG TYPE DESCRIPTION

--json boolean Output the status as JSON.

schemic new <name>

Scaffold a blank, hand-written .surql migration with up/down branches.

$ schemic new backfill_handles

FLAG TYPE DESCRIPTION

schemic check

Replay migrations in a throwaway engine and confirm they reproduce the schema. Exits non-zero on mismatch.

$ schemic check --schema

FLAG TYPE DESCRIPTION

--schema boolean Check the schema specifically.

schemic snapshot reset

Clear the migration snapshot so the next schemic gen baselines the full schema.

$ schemic snapshot reset

FLAG TYPE DESCRIPTION

schemic unlock

Release a stale migration lock left by an interrupted run.

$ schemic unlock

FLAG TYPE DESCRIPTION

Live database

schemic diff

Preview the pending change without writing a migration. Diffs against the snapshot, or a live database with --live.

$ schemic diff --live --ts

FLAG TYPE DESCRIPTION

--live boolean Diff against the running database.

--ts boolean Render the delta as TypeScript instead of SurrealQL.

--down boolean Show the rollback (reverse) direction.

--full boolean Show complete definitions, not only the delta.

--inline boolean Inline format.

-p, --patch boolean Patch-style output.

--pager boolean Page long output.

--json boolean Machine-readable output.

--watch boolean Re-run as the schema changes.

schemic push

Apply the schema directly to the database, no migration files. Alias: sync. Prunes stale objects by default.

$ schemic push --dry-run

FLAG TYPE DESCRIPTION

--dry-run boolean Show what would change without applying.

--no-prune boolean Apply additions and changes only; keep stale objects.

--watch boolean Re-push as the schema changes.

schemic pull

Introspect the database and update your s.* files to match. Previews by default; non-destructive.

$ schemic pull --write

FLAG TYPE DESCRIPTION

--write boolean Apply the preview to your .ts files.

--merge boolean Keep local-only entities; apply the database's changes alongside them.

--discard boolean Mirror the database exactly, dropping local-only definitions.

schemic seed

Run the project's seed script (database/seed.ts) with a connected client.

$ schemic seed

FLAG TYPE DESCRIPTION

Global flags

These apply to every command that connects to a database. Each overrides the matching schemic.config.ts value, which in turn falls back to environment variables.

Flag	Description
--url <url>	Database endpoint, e.g. ws://localhost:8000.
--namespace <ns>	Target namespace.
--database <db>	Target database.
--username <user>	Auth username.
--password <pass>	Auth password.
--auth-level <level>	Sign-in level: root, namespace, or database.
-c, --config <path>	Path to the config file.
--[no-]tables	Include or exclude tables from the operation.
--[no-]functions	Include or exclude functions.
--[no-]access	Include or exclude access definitions.

Where to go next

• Generate & run migrations — the workflow these commands support.
• Configuration — the config file in full.
• The migration model — migrate vs push vs pull.