SurrealKit

A skill for driving SurrealKit, SurrealDB's schema-management and migration CLI.

SurrealKit keeps a SurrealDB database in sync with .surql schema files. It provides two complementary workflows — a fast declarative sync for development and controlled, phased rollouts for shared and production databases — plus seeding, type generation, and a declarative testing framework.

When to use this skill

Reference these guidelines when:

• Scaffolding a new SurrealDB project (surrealkit init) or authoring templates
• Applying schema changes in development (surrealkit sync)
• Planning, executing, or rolling back production migrations (surrealkit rollout)
• Generating JSON or TypeScript types from a live schema (surrealkit typegen)
• Writing or running declarative tests for schemas, permissions, or API endpoints (surrealkit test)

This skill covers the SurrealKit tool itself. To write the actual schema, seed, and query statements that go in .surql files, use the surrealql skill.

Installation

Command map

Run surrealkit <command> --help to confirm available flags for an installed version.

Connection & config

Global flags work on every command and resolve in this order (highest wins): CLI flags > system env vars > .env file > defaults.

surrealkit --host http://localhost:8000 --ns my_ns --db my_db \
  --user root --pass root --auth-level root sync

The project root holds surrealkit.toml with [variables] and [typegen] sections.

Template variables

Use ${VAR_NAME} tokens in any .surql file (schema, seed, or rollout SQL). Names are case-insensitive. Values resolve in order (highest wins):

1. --var KEY=VALUE CLI flag (repeatable)
2. SURREALKITVAR<KEY> environment variable
3. [variables] section in surrealkit.toml

# surrealkit.toml
[variables]
schema_prefix = "myapp"
talent_username = "talent_rw"

surrealkit sync --var schema_prefix=acme --var talent_username=talent_rw

• An undefined variable is a hard error — SurrealKit never silently skips it or leaves the token in the SQL.
• Escape a literal ${...} by doubling the dollar sign: $${literal}.
• Substitution runs on sync, seed, apply, and rollout start/complete/rollback. It does not run on rollout plan/baseline/status/lint (no user SQL executes there).

Project layout

surrealkit init creates a database/ directory (override the root with --folder / SURREALDB_FOLDER):

database/
├── schema/                     # Schema definitions (.surql) — the source of truth
├── rollouts/                   # Generated rollout manifests (.toml)
├── snapshots/                  # Internal drift tracking
│   ├── schema_snapshot.json
│   └── catalog_snapshot.json
├── seed/                       # Seeding files (.surql)
├── tests/
│   ├── suites/                 # Test suites (.toml)
│   ├── fixtures/               # Test fixture data (.surql)
│   └── config.toml             # Global test config
└── setup.surql                 # One-time setup script
surrealkit.toml                 # Project config ([variables], [typegen])

Rules & conventions

• Sync vs rollout: use sync for local, preview, and other disposable databases where it is safe to match files immediately; use rollout for shared/production databases that need review, staged execution, rollback, or operator-controlled cutover.
• Schema files are the source of truth. sync creates, updates, and prunes SurrealKit-managed objects to match database/schema/.
• Schema files should contain DEFINE/REMOVE statements. Allow other statements (INSERT, UPDATE, CREATE) only with --allow-all-statements, which disables catalog entity tracking.
• Store SurrealQL in files with the .surql extension. Validate and format generated SurrealQL with the tools described in the surrealql skill (surreal validate, npx @surrealdb/surql-fmt).
• SurrealKit is young and evolving; confirm command surfaces against surrealkit --help and the README.

References

• Project scaffolding and templates — [references/init-templates.md](references/init-templates.md)
• Development sync and production rollouts — [references/sync-rollouts.md](references/sync-rollouts.md)
• Type generation (JSON and TypeScript) — [references/typegen.md](references/typegen.md)
• Declarative testing framework — [references/testing.md](references/testing.md)