Project templates

surrealkit init scaffolds a new project from a template and lets you choose which optional features to include. It always writes the base project layout first, then copies in the schema, seed, and test files for the features you select.

surrealkit init

In a terminal this shows a checklist of the template's features. Pick the ones you want and SurrealKit writes their files into database/.

Base layout

Every init creates the base project regardless of which features you choose:

database/
├── schema/        # .surql schema definition files
├── rollouts/      # rollout manifests (generated)
├── snapshots/     # schema and catalog snapshots
├── seed/          # optional seed data
├── tests/         # test suites and config
└── setup.surql    # runs before sync
surrealkit.toml    # project configuration

Choosing features without a prompt

When there is no terminal (such as CI), or when you pass any of the flags below, init runs without prompting:

surrealkit init --feature organizations --feature teams
surrealkit init -y
surrealkit init --minimal

A feature can depend on other features. Selecting one adds what it requires, and init prints what it added.

Using your own template

Point --from at a local path or a git repository instead of the bundled template, or pick a bundled template by name with --template:

surrealkit init --from ./path/to/template
surrealkit init --from https://github.com/your-org/your-template.git
surrealkit init --from https://github.com/your-org/your-template.git#v1.0.0
surrealkit init --template default

Git sources are cloned with git clone --depth 1, so git must be on your PATH. Pin a branch, tag, or commit with #rev, and target a subdirectory with #rev:subdir.

Template layout

A template is a directory with a template.toml manifest plus the files each feature contributes:

schema_version = 1
name = "default"
display_name = "My starter"
description = "Shown above the feature checklist"

[[features]]
id = "organizations"
name = "Organizations"
description = "Shown next to the feature in the checklist"
default = false
schema   = ["schema/organization/organization.surql"]
seed     = ["seed/organization_permissions.surql"]
suites   = ["tests/suites/organization.toml"]
fixtures = ["tests/fixtures/organization_seed.surql"]

[[features]]
id = "teams"
name = "Teams"
requires = ["organizations"]
schema = ["schema/team/team.surql"]

Each feature lists the files it adds, grouped by where they land:

• •

  schema files are copied into database/schema/

• •

  seed files into database/seed/

• •

  suites files into database/tests/suites/

• •

  fixtures files into database/tests/fixtures/

Set default = true to pre-check a feature in the prompt and include it with -y. Use requires to declare dependencies on other features.

Bundled template

The bundled default template provides an organisation and access-control model with four opt-in features:

• •

  Organizations: organisations, roles that bundle permissions, a per-app permission catalogue, employees, and invitations.

• •

  Teams: teams within an organisation, with per-member roles.

• •

  Organization units: a department and region hierarchy with unit-scoped permissions.

• •

  Subsidiaries and delegation: parent and child organisations with cross-org delegated permissions.

Teams, units, and subsidiaries each require the organizations feature.

Next steps

• •

  New databases: start a fresh project with SurrealKit

• •

  Sync: push your scaffolded schema to a database

• •

  Testing: run the test suites the template scaffolded