spacetimedb-cli

SpacetimeDB CLI

当用户需要关于 spacetime CLI 工具的帮助时使用此技能，例如初始化项目、构建模块、发布数据库、查询数据、管理服务器或排查 CLI 问题。

快速参考

项目初始化与开发

# 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|unrealcpp --out-dir ./bindings --module-path ./server

发布与部署

# 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 --clear-database --yes

数据库交互

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

# Call reducers
spacetime call my-database my_reducer '{"arg1": "value", "arg2": 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
spacetime describe my-database --json
spacetime describe my-database table users --json
spacetime describe my-database reducer my_reducer --json

数据库管理

# List databases
spacetime list

# Delete database
spacetime delete my-database

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

服务器管理

# 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

身份验证

# Login (opens browser)
spacetime login

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

# Show login status
spacetime login show

# Logout
spacetime logout

默认服务器

名称	URL	描述
maincloud	https://maincloud.spacetimedb.com	生产云（默认）
local	http://127.0.0.1:3000	本地开发服务器

常见工作流

新项目设置

# 1. Login
spacetime login

# 2. Create project
spacetime init my-game --lang rust
cd my-game

# 3. Start dev mode (auto-rebuilds and publishes)
spacetime dev

本地开发

# Start local server (in separate terminal)
spacetime start

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

# Query local database
spacetime sql my-db --server local "SELECT * FROM players"

生成客户端绑定

# After building module
spacetime build
spacetime generate --lang typescript --out-dir ./client/src/bindings --module-path .

# Or use dev mode which auto-generates
spacetime dev --client-lang typescript --module-bindings-path ./client/src/bindings

常用标志

标志	简写	描述
--server	-s	目标服务器（昵称、主机名或 URL）
--yes	-y	非交互模式（跳过确认）
--anonymous		使用匿名身份
--module-path	-p	模块项目的路径

故障排查

“未登录”

spacetime login
# Or use --anonymous for public operations

“服务器无响应”

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

“架构冲突”

# Clear data and republish
spacetime publish my-db --clear-database --yes

“构建失败”

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

模块语言

服务端（模块）： Rust、C#、TypeScript、C++ 客户端 SDK： TypeScript、C#、Rust、Python、Unreal Engine CLI generate 目标： TypeScript、C#、Rust、Unreal C++

说明

• 许多命令标记为 UNSTABLE，可能会发生变化
• 除非另行配置，否则默认服务器为 maincloud
• 在脚本中使用 --yes 标志，以避免交互式提示
• 开发模式会监视文件，并在文件发生变化时自动重新构建