Genarrative/.codex/skills/spacetimedb-cli/SKILL.md

name, description

name	description
spacetimedb-cli	SpacetimeDB 2.5 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification.

SpacetimeDB CLI

Use this skill when working with the spacetime CLI in Genarrative. Prefer repository scripts when they exist, and keep every operation pinned to an explicit target server or local process.

Genarrative Rules

• Do not rely on the default SpacetimeDB cloud target. Pass --server or --server-url explicitly in scripts, docs, smoke tests, and manual troubleshooting.
• Do not introduce maincloud / MAINCLOUD commands, env vars, or docs. Treat old references as historical residue.
• Do not use spacetime --root-dir in manual commands or docs. Use project scripts, --data-dir, explicit --server, or the configured running service.
• For repository version upgrades, update server-rs/Cargo.toml exact pins, regenerate bindings, and verify the actual CLI/runtime version. Do not treat a local CLI reinstall as a repo upgrade.
• For host upgrades, verify the running service binary, not just shell PATH: systemctl show ... MainPID -> /proc/$pid/exe --version -> /v1/ping.

Core Commands

# Build module
spacetime build
spacetime build --debug

# Publish to an explicit server
spacetime publish my-database --server http://127.0.0.1:3101 --yes=migrate,break-clients

# Destructive publish only when explicitly intended
spacetime publish my-database --server http://127.0.0.1:3101 --delete-data=always --yes=delete-data,migrate

# Delete data only for breaking schema conflicts
spacetime publish my-database --server http://127.0.0.1:3101 --delete-data=on-conflict --yes=migrate

# Generate bindings
spacetime generate --lang typescript|csharp|rust|unrealcpp --out-dir ./bindings --module-path ./server

Genarrative Local Workflow

# Prefer project wrappers
npm run dev:spacetime
npm run dev:api-server
npm run spacetime:generate

# Query local database
spacetime sql my-db --server http://127.0.0.1:3101 "SELECT * FROM players"

# Logs
spacetime logs my-db --server http://127.0.0.1:3101 -f

Database Interaction

# SQL / describe
spacetime sql my-db --server http://127.0.0.1:3101 "SELECT * FROM users"
spacetime describe my-db --server http://127.0.0.1:3101 --json
spacetime describe my-db table users --server http://127.0.0.1:3101 --json

# Reducer/procedure calls. Arguments are positional JSON values.
spacetime call --server http://127.0.0.1:3101 my-db my_reducer '"value"' '123'

# 2.5 accepts hex strings for Identity arguments without full JSON tuple syntax.
spacetime call --server http://127.0.0.1:3101 my-db reducer_needing_identity 0xabc123...

# Subscribe from CLI
spacetime subscribe my-db "SELECT * FROM users" --num-updates 10 --server http://127.0.0.1:3101

Server & Auth

spacetime server list
spacetime server add local --url http://localhost:3000 --default
spacetime server add genarrative-dev --url http://127.0.0.1:3101
spacetime server ping genarrative-dev

spacetime login
spacetime login --token <token>
spacetime login show
spacetime logout

Version & Runtime Verification

# CLI resolution can be misleading; compare all candidates when diagnosing.
type -a spacetime
spacetime --version
spacetime version list

# Verify a systemd service binary actually changed.
pid="$(systemctl show spacetimedb.service -p MainPID --value)"
readlink -f "/proc/${pid}/exe"
"/proc/${pid}/exe" --version
curl -fsS http://127.0.0.1:3101/v1/ping

Flags

Flag	Description
--server, -s	Target server nickname, host, or URL
--yes, -y	Non-interactive prompt skipping; in 2.5 prefer scoped values
--delete-data, -c	Publish data policy: always, on-conflict, or never
--module-path, -p	Module project path
--bin-path, -b	Publish/generate from compiled wasm
--no-config	Ignore spacetime.json
--env	Select config file layering environment

Troubleshooting

Not Logged In

spacetime login

Server Not Responding

spacetime server ping <server>
curl -fsS http://127.0.0.1:3101/v1/ping

For local Genarrative work, start SpacetimeDB first with npm run dev:spacetime, then start npm run dev:api-server.

Schema Conflict

spacetime publish my-db --server http://127.0.0.1:3101 --delete-data=on-conflict --yes=migrate

Use --delete-data=always only with explicit approval.

Version Mismatch

rg -n 'spacetimedb' server-rs/Cargo.toml
spacetime --version
spacetime version list
pid="$(systemctl show spacetimedb.service -p MainPID --value)"
"/proc/${pid}/exe" --version

Notes

• Procedure calls are stable in 2.5; module HTTP handlers/webhooks, unstable view features, and RLS remain behind unstable gates per release notes.
• 2.5 fixes publish --delete-data config fallback so spacetime.json can provide the database name.
• Genarrative scripts should pass --server or --server-url explicitly instead of relying on CLI defaults.