CLI reference

Every spky command, grouped by what you're trying to do. Run spky <command> --help for full flags.

spky --help

Commands read sp00ky.yml from the current directory. Pass --path <dir> to point at a project somewhere else, and spky <command> --help for the flags of any single command.

Project & dev loop

Repository performance benchmark

The repository also contains spooky-bench, a separate developer tool in apps/benchmark. Its whitepawn suite measures scheduler and SSP bootstrap, 50-row live windows with related player names, scrolling with twenty retained windows, and propagation during steady writes and import bursts. It uses deterministic synthetic chess-game libraries and real database changefeeds. Measured startup, latency, throughput, memory and backlog results are published in the WhitePawn performance baseline, including completed cases and resource-limited tiers.

# Run from the repository root with Docker running.
cargo build --release -p sp00ky-cli -p scheduler -p ssp-server
pnpm -F @spooky-sync/benchmark build
pnpm -F @spooky-sync/benchmark test
node apps/benchmark/dist/index.js whitepawn --smoke
node apps/benchmark/dist/index.js whitepawn --profile standard

--smoke runs compact and PGN-heavy 10K-game cases with short load phases. --profile standard runs 100K compact, 1M compact and 1M PGN-heavy cases. The default large profile adds 10M compact games. Each case starts a disposable SurrealDB container and fresh scheduler/SSP processes; Docker must be running.

The benchmark records registration and publication latency separately and checks published root/child references and record versions. Scroll evictions remove both published references and durable registration metadata. Bounded checks between phases verify the retained registration ids and graph/follower counts. Raw reports include CPU, memory, write and readiness samples. Capacity checks include games added by load phases and reserve disk and memory headroom. Without a smaller measured PGN-heavy case, PGN projections use measured compact costs plus payload allowances as a floor, keeping the larger value for each resource against the initial PGN estimate. A preflight resource-limited result records a conservative estimate, not an observed out-of-memory failure, and produces a nonzero exit rather than a successful benchmark result.

Use whitepawn --help for binary paths, image, readiness timeout and output options. The default image is surrealdb/surrealdb:v3.1.5. --startup-timeout-secs bounds startup and publication-readiness waits, including propagation probes and load catch-up, at 3,600 seconds per wait by default. It is separate from the overall run duration. --schema accepts a custom source schema compatible with the chess fixture. The repository’s apps/benchmark/README.md describes the dataset matrix, load phases, measurements and existing focused benchmark suites. This command is invoked with spooky-bench, not spky.

Adding things to a project

Running unattended: -y / --yes

Every subcommand accepts -y / --yes, and SPKY_YES=1 does the same from the environment. It answers confirmation prompts without asking, so a command never sits waiting for a keypress.

This is the flag a CI job or a coding agent should pass. A pipe is easy for the CLI to detect, but an agent usually runs commands on a pseudo-terminal, where the prompt renders normally and then waits forever for input nothing can send.

The two kinds of question get different answers, because “yes to everything” is not what anyone means:

The last row is deliberate. --yes is the flag that gets added to every command by reflex, which makes it the wrong thing to arm “delete everything” with. Those two take the project’s name instead:

spky project destroy --confirm my-project
spky backup reset --confirm my-project          # still takes its backup first
spky backup reset --confirm my-project --no-backup

--yes also switches the guided flows (spky login, picking or creating a project, billing setup) to their unattended path. They lead into pickers and browser logins that no flag can answer, so instead of opening one they stop with the exact command or environment variable to use.

Operating a running system

Cloud

Restarting containers

spky restart recreates containers in place. With no target it restarts the scheduler and its SSPs, leaving backends, frontends and SurrealDB running.

spky restart                 # scheduler + SSPs
spky restart db              # SurrealDB only (prompts first)
spky restart ssp scheduler   # several roles at once
spky restart gameanalysis    # one backend, by app name
spky restart --all-backends  # every backend app
spky restart --upgrade       # newest scheduler/SSP build first (unless version: pins them)
spky restart --clean         # also wipe the scheduler's replica + WAL
spky restart db -y           # CI: skip the SurrealDB prompt

What --upgrade, --clean and --surreal do at the container level is spelled out in Admin dashboard, which offers the same three actions from a browser.

Web Push

spky push inspects and drives Web Push as root, against the local dev database by default or the cloud deployment with --cloud (or any database with --url, --namespace, --database, --username, --password), like spky schedules.

send takes:

spky push status                                    # local dev stack
spky push status --cloud                            # the deployment
spky push send --to user:abc --title "Hello" --body "Push works"
spky push send --to user:abc,user:def --title "Maintenance at 22:00" --at 2h
spky push send --to user:abc --data '{"conversation":"c1"}'   # a nudge
spky push devices user:abc
spky push sync --cloud                              # store push: without a deploy

Migrating a deployment

spky migrate prod applies pending migrations plus the internal Sp00ky schema to your cloud deployment, without deploying anything else. It resolves the SurrealDB URL and root password from your login and the slug in sp00ky.yml, and reads the mode, namespace and database from sp00ky.yml too, so there are no connection flags to pass.

A pay-as-you-go project’s own database is reached as root, like a VM project’s. A project on the retired free plan has no root login: its data lives in a namespace of the shared free database. There migrate prod, spky release and every --cloud command (migrate, query, jobs, flag, schedules, workflows, push) sign in as the project’s namespace-level owner user, the one spky project credentials prints, and work in the namespace and database the project was given there. --namespace cannot reach outside it.

Raise SPKY_DB_HTTP_TIMEOUT_SECS when a large migration exceeds the 120 second per-request deadline. Migrations

Flags worth memorising

spky dev --clean            # rebuild SSP/scheduler state, keep your data
spky dev --clean-db         # also wipe the database
spky dev --verbose          # stream all SurrealDB/SSP/scheduler logs
spky deploy --only api,web  # deploy a subset of apps
spky deploy --upgrade       # also move SSP/scheduler to the newest build (unless version: pins them); pay as you go: SurrealDB 3 -> 4 after a backup
spky doctor --json          # machine-readable health check
spky query --cloud '…'      # run SurrealQL against production
spky logs --since 1h --grep 'error'