Command line¶
skywalker is the headless engine: MCP server, renderer, simulator, Wander compiler, tool runner, studio runner, packager and movie renderer in one binary (build/<preset>/bin/skywalker). The help texts below are captured from the binary itself.
| Command | Purpose |
|---|---|
skywalker mcp |
Run the MCP server: on stdio with a headless engine, bridged to a running editor (--attach), or whichever is available (--auto, what agent configs use). |
skywalker serve |
Run a headless engine that serves the agent socket like the editor, so several clients (Python agents, mcp --attach, call --attach) share one engine. |
skywalker setup |
Install the MCP entry, skills, subagents and commands for Claude Code, Codex, Gemini CLI or Cursor. |
skywalker render |
Render a scene file to a PNG (supersampled with --samples; --annotate labels entities with their ids). |
skywalker run |
Simulate a scene deterministically for N ticks, print the logs, optionally render the last frame. |
skywalker check |
Compile a .wander file exactly as the engine would and print diagnostics. |
skywalker call |
Run one tool on a scene or project, or on the running editor with --attach. |
skywalker tools |
List every tool, as text, Markdown or the JSON that MCP clients receive. |
skywalker studio |
Inspect the studio (roster, board, feedback, loops) or run a loop headless with your API keys. |
skywalker build |
Package a project as a standalone macOS app around the player. |
skywalker movie |
Render a cinematic offline to H.264, HEVC, ProRes or PNG frames. |
skywalker legal |
Print the Terms of Use, the Privacy Notice or the license embedded in the binary, or record acceptance for headless and CI use (--accept). |
skywalker version |
Print the engine version. |
Usage¶
skywalker 0.1.0 — a game engine built for AI agents
usage:
skywalker mcp [--project DIR] [--scene FILE] MCP server on stdio
skywalker mcp --attach [SOCKET] bridge to a running editor
skywalker mcp --auto [--project DIR] bridge to the editor if it runs, else headless
skywalker serve [--project DIR] [--scene FILE] [--socket PATH] [--lifeline]
headless engine serving the agent socket (like the editor)
skywalker setup <claude|codex|gemini|cursor|all> [--project DIR] [--global] [--dry-run] [--print] [--no-skills]
install the MCP server entry, skills, subagents and commands
skywalker render SCENE -o out.png [--width W] [--height H] [--annotate] [--scene-camera] [--samples N]
skywalker run SCENE [--ticks N] [-o out.png]
skywalker check FILE.wander [--project DIR] [--disassemble] [--format]
skywalker call TOOL [JSON] [--scene FILE] [--project DIR] [-o image.png]
skywalker call TOOL [JSON] --attach [--as NAME] [--socket PATH] (on the running editor)
skywalker tools [--markdown|--json] [--project DIR]
skywalker studio status|agents|board|feedback|loops --project DIR
skywalker studio run --project DIR --loop NAME [--iterations N] [--dry-run] [--yes]
skywalker build --project DIR --out DIR [--name N] [--icon F.png] [--release] [--all-assets] package a macOS app
skywalker movie SCENE [JSON] -o out.mp4 [--sequence S] [--resolution 1080p] [--fps N] [--samples N]
[--shutter F] [--simulate] [--clay|--sketch] [--resume] ... render a cinematic (movie --help)
skywalker legal [terms|privacy|license|licensing] [--accept] [--status] [--json]
Terms of Use, Privacy Notice, license; --accept records acceptance
skywalker version
skywalker mcp¶
Run the MCP server: on stdio with a headless engine, bridged to a running editor (--attach), or whichever is available (--auto, what agent configs use).
skywalker mcp [--project DIR] [--scene FILE] MCP server on stdio
skywalker mcp --attach [SOCKET] bridge to a running editor
skywalker mcp --auto [--project DIR] bridge to the editor if it runs, else headless
skywalker serve¶
Run a headless engine that serves the agent socket like the editor, so several clients (Python agents, mcp --attach, call --attach) share one engine.
usage: skywalker serve [--project DIR] [--scene FILE] [--socket PATH] [--lifeline] [--quiet]
A headless engine serving the agent socket (like the editor). Attach with
`skywalker mcp --attach PATH`, the Python agent layer (sky-agents), or `call --attach --socket PATH`.
skywalker setup¶
Install the MCP entry, skills, subagents and commands for Claude Code, Codex, Gemini CLI or Cursor.
usage: skywalker setup <claude|codex|gemini|cursor|all> [options]
Installs the MCP server entry (pointing at this binary), the skywalker-* skills, studio-role subagents,
workflow commands and a guidance block for the tool. Existing configs are merged, never replaced;
files that change are backed up under <root>/.skywalker/setup-backups/.
options:
--project DIR project to configure (default: current directory)
--global configure your user-level config (~/.claude, ~/.codex, ~/.gemini, ~/.cursor) instead
--dry-run show what would change (with diffs); write nothing
--print print the MCP entry to paste by hand; write nothing
--no-skills only the MCP server entry
--mode MODE auto (default: editor if running, else headless), attach, or headless
--binary PATH path to write for the skywalker executable (default: this binary)
--home DIR use DIR as the home directory for --global (for tests); external commands are printed, not run
--verbose list every file instead of a summary
skywalker render¶
Render a scene file to a PNG (supersampled with --samples; --annotate labels entities with their ids).
skywalker render SCENE -o out.png [--width W] [--height H] [--annotate] [--scene-camera] [--samples N]
skywalker run¶
Simulate a scene deterministically for N ticks, print the logs, optionally render the last frame.
skywalker check¶
Compile a .wander file exactly as the engine would and print diagnostics.
skywalker call¶
Run one tool on a scene or project, or on the running editor with --attach.
skywalker call TOOL [JSON] [--scene FILE] [--project DIR] [-o image.png]
skywalker call TOOL [JSON] --attach [--as NAME] [--socket PATH] (on the running editor)
skywalker tools¶
List every tool, as text, Markdown or the JSON that MCP clients receive.
skywalker studio¶
Inspect the studio (roster, board, feedback, loops) or run a loop headless with your API keys.
usage: skywalker studio status|agents|board|feedback|loops --project DIR
skywalker studio run --project DIR --loop NAME [--iterations N] [--goal TEXT]
[--dry-run | --mock SCRIPT.json] [--yes] [--scene FILE] [--no-save] [--verbose]
skywalker build¶
Package a project as a standalone macOS app around the player.
usage: skywalker build --project DIR --out DIR [options]
Builds DIR/<Name>.app: the player, the scenes, the assets they reference, scripts, the compiled native
module, Info.plist, icon and an ad-hoc code signature. Settings come from the project's game.json.
options:
--project DIR the project (default: current directory)
--out DIR folder to write the app into (required)
--name NAME app name (default: game.json title)
--icon FILE.png app icon, 1024x1024 recommended (default: game.json icon)
--release strip the player's symbols (smaller app)
--all-assets ship every asset, not only the referenced ones
--version X.Y.Z --bundle-id com.you.game --scene FILE override game.json
--no-sign skip the ad-hoc code signature
--no-native do not compile native/*.cpp
--player PATH player executable to bundle (default: skywalker-player next to this binary)
--dry-run list what would ship; write nothing
--json machine-readable report
skywalker movie¶
Render a cinematic offline to H.264, HEVC, ProRes or PNG frames.
usage: skywalker movie SCENE [JSON] [options]
Renders a cinematic offline: a sequence, an inline camera path (JSON "camera") or the scene camera.
JSON takes every movie_render argument; the options below override it.
options:
--project DIR the project (default: current directory)
-o, --output PATH .mp4 (H.264), .mov (ProRes 422 HQ) or a folder / name_####.png (repeatable)
--codec C codec of the -o before it: h264 | hevc | prores | prores4444 | png
--bitrate MBPS H.264 / HEVC bitrate of the -o before it
--sequence NAME sequence entity or .sequence.json
--camera-entity NAME look through this camera
--start S --end S --duration S time range in seconds
--fps N 24 (default), 30, 60...
--resolution R 720p | 1080p (default) | 1440p | 4k (or --width W --height H)
--samples N samples per frame (default 8)
--shutter F motion blur: open fraction of the frame (0.5 = 180 degrees)
--shutter-samples N sub-frames across the shutter
--simulate run the game simulation (scripts, physics)
--clay | --sketch clay or pencil-sketch look
--quality Q full | balanced | fast
--warmup N frames rendered before the first one (default 4)
--resume continue an interrupted PNG sequence
--quiet no progress lines
Ctrl-C stops after the current sub-frame; written frames and the video so far are kept.
skywalker legal¶
Print the Terms of Use, the Privacy Notice or the license embedded in the binary, or record acceptance for headless and CI use (--accept).
usage: skywalker legal [terms|privacy|license|licensing] [--accept] [--status] [--json]
Prints Skywalker's Terms of Use, Privacy Notice and license summary (the copies embedded in this binary).
Nothing is sent anywhere; automation never waits for acceptance.
terms|privacy|license|licensing print one document (license = full LICENSE text,
licensing = plain-language summary and third-party notices)
--accept record that you accept the Terms of Use and acknowledge the Privacy Notice
(for headless and CI use; the editor asks on first launch)
--status versions and acceptance state only
--json machine-readable output (the legal_info tool payload)
skywalker version¶
Print the engine version.