@catapultgames/cli

Alpha command-line tool for creating, validating, playtesting, and deploying turn-based web games.

Getting the CLI

Published as @catapultgames/cli - same npm scope as the SDK, separate package (the CLI has real dependencies, like playwright-core, that a game's own runtime install has no business pulling in - see docs/RELEASING.md).

npx @catapultgames/cli create my-game
cd my-game

Or install it globally so platform is always on your PATH:

npm install -g @catapultgames/cli
platform create my-game

The generated project depends only on the public @catapultgames/sdk package, not on the CLI or anything monorepo-internal (verified by bun run smoke:creator-flow, which builds and plays a project outside the repo entirely, against a real npm install).

Working from a repo checkout instead (contributing to the CLI itself, or before a given change is published): bun apps/cli/src/index.ts create my-game runs the same code from source - bin/platform.mjs prefers src/ when present for exactly this reason.

Commands

• platform --version prints the installed CLI package version.
• platform version prints the CLI version, the SDK version generated projects pin, and the protocol version - three distinct numbers, see docs/RELEASING.md.
• platform create <name> copies the blank scaffold.
• platform validate --project <path> checks game.toml and required files.
• platform playtest --profile four_player --project <path> starts the local room host and Playwright sessions. Human and fake seats begin in the ready check, while manifest-configured agents retain automatic readiness.
• platform playtest --report out --video --report-actions 20 --screenshots-at 0,5,10,20 --project <path> runs a headless visual simulation, drives legal actions, and writes per-seat screenshots, step screenshots, .webm videos, and report.json timeline metadata. Reports connect every seat, ready unready seats through the SDK, and wait for the started game view before driving actions. --report-actions is one global accepted-action budget: the deterministic driver rotates across seats that can currently act and fails only when no active seat has a playable non-chat action. Use --video-size 1280x720 to force a recording size; otherwise each launch profile viewport is used.
• platform playtest --lan --project <path> binds the room host and play shell to your LAN address (auto-detected IPv4) and prints per-seat LAN URLs, so phones/laptops on the same wifi can join. --host <ip> picks the interface explicitly on multi-interface machines and overrides --lan auto-detection. Security note: both flags expose the playtest server to your local network; the default stays loopback-only (127.0.0.1).
• platform deploy --dry-run --project <path> writes .platform-build.
• platform deploy --project <path> --api <url> --token <token> uploads to the hosted alpha API.

The CLI imports shared protocol and deploy types from @platform/contracts. Its own bin/platform.mjs runs under plain Node (>= 22.18) or bun: under bun in this repo it prefers src/, and otherwise uses the compiled dist/ (an npm install, where files ships dist but not src) - see the comment in bin/platform.mjs before changing that resolution order.