Docs ▸ Start
Commands
init
Detects the game and writes gameshipper.json. It finds index.html (or the first .html file), an icon at icon.png, art/icon.png, assets/icon.png or public/icon.png, and the art for the store images at art/key-art.png (or .jpg) and art/logo.png. Steam needs a square PNG of at least 1024x1024, so an icon that isn't one is left out with an ICON_UNSUITABLE warning. If package.json has a build script and a bundler (Vite, Parcel, webpack, esbuild, Rollup), Gameshipper runs npm run build before every play and build and packages dist/. It also adds .gameshipper/, out/ and .sdk/ to .gitignore, creating one if the folder is a git repository without it.
| Flag | |
|---|---|
--name <name> |
Game name shown in windows and stores. |
--app-id <id> |
Steam App ID (default 480, Valve's test app). |
--icon <png|none> |
Square PNG icon, at least 1024x1024. |
--key-art <file|none> |
Key art for the store images: PNG or JPEG, 3840x2160 recommended. |
--logo <png|none> |
Game logo on a transparent background, for the store images. |
--bundle-id <id|none> |
Bundle ID like com.yourname.yourgame. Adds the ios and android targets (see iOS and Android). It can never change once the game is in a store. |
--entry <file> |
The game's HTML file (default: detected). |
--build-command <cmd> |
Command that builds the game (default: detected). |
--output-dir <dir> |
Folder the build command writes. |
--force |
Overwrite an existing gameshipper.json. |
In a terminal, init asks for the name, App ID, icon, key art, logo and a bundle ID for iOS and Android. With --yes or --json, or when stdin isn't a terminal, it uses the flags and what it detected instead.
play
Runs the game in the same shell the builds use. The window stays a window even when gameshipper.json asks for fullscreen; F11 or Alt+Enter toggles fullscreen. F12 saves a 1920x1080 store screenshot to out/store/screenshots/ (the window flickers while it's taken). Saves go to .gameshipper/play-data/, so testing never touches a real install's saves.
| Flag | |
|---|---|
--smoke |
Run for a few seconds, quit, and report errors, missing files, internet use and crashes. |
--seconds <n> |
How long a smoke run lasts after the page loads (default 5, at most 600). Implies --smoke. |
--screenshot <s,s,...> |
Save 1920x1080 store screenshots this many seconds after the page loads, then quit, e.g. --screenshot 5,10,15,20,25 (up to 20 times, each at most 600). |
--fullscreen |
Honour window.fullscreen from gameshipper.json. |
--packaged |
Run this computer's build from out/ (made by build) as it is, instead of preparing the game folder. --packaged --smoke tests the real build. With your own App ID, Steam relaunches it as it would any build started outside Steam. |
--detach |
Start the game and return at once, leaving it running (its output goes to the run log). Not with --smoke, --seconds or --screenshot. |
--frozen-lock |
Fail instead of accepting changed or new CDN files; for CI. |
--steam-sdk <path> |
Your Steamworks SDK zip or folder (see Steam). |
build
Builds desktop apps into out/<target>. For a game named "Spinning Cube" that's out/windows/Spinning Cube.exe, out/mac/Spinning Cube.app and out/linux/spinning-cube. One target failing never stops the others.
On Linux, spinning-cube is the game's launcher, a small shell script, and spinning-cube-bin next to it is the game itself. Players, Steam's launch option and Gameshipper all start the launcher, with no arguments needed: it starts the game with --no-sandbox. Linux builds run without Chromium's sandbox (a game is its developer's own files, and its window can't be taken anywhere else), and Chromium only takes that from the command line: on Ubuntu 24.04 and later, where that sandbox can't start for a game in a folder, spinning-cube-bin started by itself stops before its window opens. The launcher works through symbolic links to it, from any folder and with spaces in its path, and hands its process to the game, so signals and the exit code are the game's.
| Flag | |
|---|---|
--target <list> |
Comma-separated subset of the configured targets, e.g. --target windows,linux. |
--frozen-lock |
Fail instead of accepting changed or new CDN files; for CI. |
--steam-sdk <path> |
Your Steamworks SDK zip or folder (see Steam). |
targets defaults to windows, mac and linux; with ios and android (which init --bundle-id adds) it also writes an Xcode project to out/ios and an Android Studio project to out/android (see iOS and Android). On a Mac, the Mac app is signed, and notarized when your Apple credentials are set (see Mac signing and notarization).
Every build also makes the store images in out/store/, whatever --target says.
check
Launches the latest build for this computer once, for 15 seconds (--seconds to change), with the network blocked and the page laid out at Steam Deck size (1280x800), then closes its window the way a player would. It also looks at every build and at out/store/, and reports 18 checks:
| Group | What |
|---|---|
| Offline | nothing is loaded from the internet (every blocked address is listed) |
| Launch | it starts, has no console errors or missing files, draws a non-uniform frame (with a warning when it's mostly one colour, like a loading screen), and exits with code 0 when its window closes; builds for other operating systems are listed as built, not launched here |
| Steam Deck | at 1280x800 nothing is cut off, no text runs past the screen edge and no scrollbars appear; it reads a gamepad (while running, or in its own code: engine and library files aren't searched); text fields are listed |
| Review | a build for every desktop target, no steam_appid.txt, the Mac build signed and notarized, a custom icon, your own App ID |
| Store | all eight images at their exact sizes and made from the current key art, logo and focus, at least five 1920x1080 screenshots, and reminders about the trailer and Steam's AI disclosure |
Run it after build: it never builds anything itself. The Deck-size frame is saved as .gameshipper/check/frame.png and the full report as .gameshipper/check/report.json. Without Apple credentials a Mac build is only ad-hoc signed, so on a Mac review.mac-signing fails with CHECK_MAC_NOT_NOTARIZED until you sign and notarize it.
The network block stops the game's requests (each is listed in offline.requests) and its WebRTC connections (not listed). A plugin's requests through Electron's net module are blocked and listed too, but its Node networking in Electron's main process (http, https, fetch) isn't blocked, and neither is WebTransport: offline.requests never sees those.
| Flag | |
|---|---|
--seconds <n> |
How long the game runs with the network blocked (default 15, at most 600). |
publish
Uploads the builds in out/ to Steam, itch.io and GitHub Releases: by default to each one gameshipper.json sets up (see Publishing). Every desktop target must be built first. One destination failing never stops the others.
| Flag | |
|---|---|
--to <list> |
Where to upload: steam, itch and github, or some of them. |
--dry-run |
Check everything and preview the uploads, uploading nothing. Steam still needs its login for this. |
--steam-user <account> |
The Steam account that uploads builds (default: steam.user). |
--branch <name> |
Steam: also set the build live on this existing beta branch (never default). |
--repo <owner/name> |
The GitHub repository to release to (default: github.repo). |
--live |
GitHub: publish the release at once instead of leaving it a draft. |
status
Shows the config, what this computer can build, the Steamworks SDK builds will use, which out/ folders exist, and the last result of init, play, build, check, publish and ci with their log paths. It succeeds for any existing folder, so it's the command to run first.
ci init
Writes .github/workflows/gameshipper.yml, a GitHub Actions workflow (see GitHub Actions). --force replaces an existing one.
mcp
Serves every command as an MCP tool over stdio (see MCP server and Claude Code plugin). --dir sets the game folder tools use by default.
help
help lists the commands, help <command> or <command> --help shows a command's flags, and help --json returns every command, flag and exit code plus the JSON Schema of gameshipper.json.
Global flags
| Flag | |
|---|---|
--json |
Print the result as JSON on stdout and nothing else. |
--verbose |
Also stream the run log to stderr. |
-y, --yes |
Never prompt; use detected defaults and flags. |
--dir <path> |
Game folder (default: the current folder). |
-h, --help |
Show help for a command. |
-v, --version |
Print the Gameshipper version. |