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 <kind> <name>

Scaffold a starter schema file for an entity at <schema>/<kind-folder>/<name>.ts — a realistic starter, not a bare stub. Surreal kinds map to folders: table → tables/, relation → relations/, view → views/, function → functions/, access → access/, event → events/, analyzer → analyzers/. (index and field are authored inline on a table, not standalone.) Requires a directory schema layout; never overwrites an existing file.

$ schemic new table user

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.

--watch boolean Poll the live database and re-pull as it changes.

--interval <seconds> number Poll interval for --watch (default 2).

schemic seed [name]

Run the project's seeds against a connection. Seeds live in database/seed/: bare schemic seed runs database/seed/index.ts (or every seed in filename order if there is none), a name runs one seed, and --all runs them all. A flat database/seed.ts still works as a single seed.

$ schemic seed [name] [--all]

FLAG TYPE DESCRIPTION

[name] string Run the single named seed (its filename without the NN- ordering prefix).

--all boolean Run every seed in database/seed/ in filename order, even when an index.ts is present.

Global flags

These apply to every command that connects to a database. Each overrides, for that command, the resolved connection from schemic.config.ts.

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.
--connection <name>	Run against a named connection from your config (default: default).
--all	Run against every connection in your config.
--[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.