spky dev

One command brings up SurrealDB, the SSP, the scheduler and your own apps, with migrations already applied.

spky dev

That’s your whole local stack. It reads sp00ky.yml, starts everything in dependency order, applies pending migrations, and streams the logs of every service into one terminal. Ctrl+C tears it all down.

👻 sp00ky dev  ·  singlenode  ·  v0.0.1

  ✓ Ports free            8666 8667
  ✓ Schema drift          in sync
  ✓ Docker network
  ✓ SurrealDB             ready · 2.1s
  ✓ Namespace / database  main/main
  ✓ Migrations            up to date
  ↷ Internal schema       unchanged
  ✓ Remote functions      → http://ssp:8667
  ✓ SSP                   started
  ✓ Apps                  web, api

  ╭──────────────────────────────────────────────╮
  │  Development environment ready               │
  │                                              │
  │  web         http://localhost:5173/          │
  │                                              │
  │  SurrealDB   http://localhost:8666           │
  │  SSP         http://localhost:8667           │
  │                                              │
  │  api         http://localhost:3001           │
  │                                              │
  │  Ctrl+C to stop  ·  errors only, --verbose for all logs │
  ╰──────────────────────────────────────────────╯

Service	Local URL	Role
SurrealDB	`http://localhost:8666`	The database. Your client connects here.
SSP	`http://localhost:8667`	Incremental view maintenance and the job runner.
Scheduler	`http://localhost:9667`	Cluster coordinator. Only in `mode: cluster`.

Any app in sp00ky.yml with a dev block starts too. See Dev servers & sidecars.

What it does on startup

Checks your schema against the database and warns about drift.
Creates the Docker network and starts SurrealDB, waiting for it to report healthy.
Ensures the namespace and database exist.
Applies pending migrations, then the internal Sp00ky schema and remote functions.
Starts the scheduler (cluster mode) and the SSP.
Starts your apps.

Flags

Flag	Effect
`--apply-migrations`	Apply pending migrations without prompting. What you want in a script.
`--skip-migrations`	Skip the migration check entirely.
`--fix-checksums`	Update stored checksums for migration files that were edited after being applied.
`--clean`	Wipe SSP and scheduler state so they re-bootstrap from SurrealDB. Your data is preserved.
`--clean-db`	Also wipe the SurrealDB volume. Implies `--clean`.
`--verbose`, `-v`	Show every log line after startup: SurrealDB / SSP / scheduler (compact-formatted) and your apps’ dev servers. Also `SPKY_VERBOSE=1`.

By default, once the stack is ready, only errors and crash traces are shown, from the infrastructure services and from your own apps alike (stack frames stay attached to their error). The ready box leads with your frontend’s URL. Declare port: on its dev: block to have it there immediately; otherwise spky dev starts the app dev servers first and reads the URL the frontend announces (vite’s Local: http://…), waiting up to 20 s for it. Backends are listed below the infrastructure rows, from their deploy.port or docker port mapping. Warnings and everything else need --verbose. Startup itself is a checklist: each step is one line that updates in place (a spinner while it runs, then ✓, ↷ for “nothing to do”, ! for “needs your attention”, ✗ for a failure with the relevant container logs underneath). When output is piped (CI, | cat) the same steps print as plain one-line entries.

--clean-db deletes your local data

--clean is the recovery tool: it clears derived state (views, snapshots) and rebuilds it from the database. --clean-db throws away the database too. Reach for --clean first. It fixes most “my query returns nothing” situations without costing you your seed data.

The edit loop

With spky dev running:

Edit .surql → the schema is regenerated, so your types update. Create a migration with spky migrate create when you’re ready to make the change durable.
Edit app code → your own dev server handles it (Vite, next dev, whatever you configured).
Something looks wrong → spky doctor in a second terminal, then spky jobs or spky logs depending on what’s stuck.

Note

Ports 8666, 8667 and 9667 must be free. spky dev checks them up front and tells you which process is holding one.

Dev servers & sidecars Start your frontend, backend and third-party containers with the stack. Environment variables What gets injected, and how to add your own. Doctor & troubleshooting The fastest way to find out what's actually broken. Migrations Create, apply and repair schema changes.

spky dev

What it does on startup

Flags

The edit loop

Next