cli

SpacetimeDB CLI

Use this skill when the user needs help with the spacetime CLI tool - initializing projects, building modules, publishing databases, querying data, managing servers, or troubleshooting CLI issues.

Quick Reference

Project Initialization & Development

# Initialize new project
spacetime init my-project --lang rust|csharp|typescript|cpp
spacetime init my-project --template <template-id>

# Build module
spacetime build                    # release build
spacetime build --debug            # faster iteration, slower runtime

# Dev mode (auto-rebuild, auto-publish, generates bindings)
spacetime dev
spacetime dev --client-lang typescript --module-bindings-path ./client/src/module_bindings

# Generate client bindings
spacetime generate --lang typescript|csharp|rust --out-dir ./bindings --module-path ./server
spacetime generate --lang unrealcpp --uproject-dir ./MyGame --module-path ./server --unreal-module-name MyGame

Client and Module Bindings

spacetime generate --bindings client (default) generates bindings for clients connecting to a database. --bindings module generates receiver bindings used inside a calling database module to call reducers in another receiving database through asynchronous IDC. Rust and TypeScript module bindings are supported; C#/C++ module bindings are not implemented yet. unrealcpp is client-only; cpp is accepted only in module mode.

In spacetime.json, each calling database's non-inherited dependencies array requires its own module-path and dependency name plus receiving-module module-path or database. A database reference resolves another target's local source/build settings in the same config; it does not fetch a running database's schema. A direct receiving module source takes precedence. Dependencies do not themselves publish receiving databases or inherit the calling module's build settings. generate <calling-database> processes both its regular generate entries (client bindings by default) and dependencies (module bindings automatically); no --bindings flag or second generate entry is needed for a dependency. For dependencies, module binding language defaults to the calling module's language and Rust/TypeScript output defaults to <calling module-path>/src/remote_bindings. Explicit config out-dir is config-relative. A regular generate entry can select "bindings": "module", but does not use dependency language or output defaults. The CLI --bindings override is allowed only when a single generation entry is selected.

dev generates only root dependencies before building the calling module, and watches their source paths. Child targets are available for source lookup, not recursive dependency generation. --skip-generate skips receiver/client generation and receiver-only watching; --skip-publish does not. See https://spacetimedb.com/docs/cli-reference/spacetime-json#receiver-dependencies for examples.

Publishing & Deployment

# Publish to Maincloud (default)
spacetime publish my-database --yes

# Publish to local server
spacetime publish my-database --server local --yes

# Clear database and republish
spacetime publish my-database --delete-data=always --yes

Database Interaction

# SQL queries
spacetime sql my-database "SELECT * FROM users"
spacetime sql my-database --interactive   # REPL mode

# Call reducers (each argument is a separate positional arg)
spacetime call my-database my_reducer '"value"' '123'

# Subscribe to changes
spacetime subscribe my-database "SELECT * FROM users" --num-updates 10

# View logs
spacetime logs my-database -f              # follow logs
spacetime logs my-database -n 100          # up to 100 log lines

# Describe schema
# (without --json, output is human-readable text)
spacetime describe my-database --json
spacetime describe my-database tables --json   # also views, reducers, procedures, routes, env, types
spacetime describe my-database tables users --json
spacetime describe my-database reducers my_reducer --json

Database Management

# List databases
spacetime list

# Delete database
spacetime delete my-database

# Rename database
spacetime rename <database-identity> --to new-name

Server Management

# List configured servers
spacetime server list

# Add server
spacetime server add local --url http://localhost:3000 --default
spacetime server add myserver --url https://my-spacetime.example.com

# Set default server
spacetime server set-default local

# Test connectivity
spacetime server ping local

# Start local instance
spacetime start

# Clear local data
spacetime server clear

Authentication

# Login (opens browser)
spacetime login

# Login with token
spacetime login --token <token>

# Show login status
spacetime login show

# Logout
spacetime logout

Default Servers

Name	URL	Description
maincloud	https://maincloud.spacetimedb.com	Production cloud (default)
local	http://127.0.0.1:3000	Local development server

Common Flags

Flag	Short	Description
--server	-s	Target server (nickname, hostname, or URL)
--yes	-y	Non-interactive mode (skip confirmations)
--anonymous		Use anonymous identity
--module-path	-p	Path to module project
--no-config		Ignore spacetime.json project configuration

Troubleshooting

"Not logged in"

spacetime login
# Or use --anonymous for public operations

"Server not responding"

spacetime server ping <server>
# For local: ensure spacetime start is running

"Schema conflict"

# Clear data and republish
spacetime publish my-db --delete-data=always --yes

"Build failed"

# Check Rust/C# toolchain
rustup show
# For Rust modules, ensure wasm32-unknown-unknown target
rustup target add wasm32-unknown-unknown

Module Languages

Server-side (modules): Rust, C#, TypeScript, C++ Client SDKs: TypeScript, C#, Rust, Unreal Engine CLI generate targets: TypeScript, C#, Rust, Unreal C++