Playform CLI (@d3x3/pf-cli)

Create, validate, pack, and upload Playform flappy game packs. Packs run on https://playform-0.web.app (Stumble or direct play URL).

Commands

playform init flappy <dir>

Create a new flappy pack from the default template in <dir>.

• <dir> — Directory to create (e.g. my-game). Must not exist or must be empty.
• Writes: manifest.json, game.js, assets/ (bird.png, bg.png, pipe.png, tap.wav, die.wav), README.md (project only; not packed).

Example:

playform init flappy my-game

playform validate [dir]

Validate a pack directory. Same rules as the backend so you fail locally, not after upload.

• [dir] — Pack directory (default: current directory).
• Checks: manifest.json exists and is valid; required fields; template flappy_v0; entry file exists; no path traversal; allowed extensions; total size ≤ limits; all referenced assets exist.
• Success: prints ✅ Pack is valid. and exits 0.
• Failure: prints errors and exits 1.

Examples:

playform validate my-game
cd my-game && playform validate

playform pack [dir] -o <zip>

Zip the pack for upload. Only manifest.json, entry file, and manifest-listed assets are included.

• [dir] — Pack directory (default: current directory).
• -o, --output <zip> — Output zip path (required).
• Excludes: README.md, .DS_Store, anything not in the manifest.
• Zip root = manifest.json, game.js, assets/ (no top-level folder).

Example:

playform pack my-game -o my-game.zip

playform upload <zip> --api <url>

Upload a pack zip to the Playform API.

• <zip> — Path to the zip file.
• --api <url> — API base URL (default: https://playform-api-507636286767.us-central1.run.app).
• Prints the returned gameId and the play URL: https://playform-0.web.app/play/<gameId>.

Examples:

playform upload my-game.zip
playform upload my-game.zip --api https://playform-api-507636286767.us-central1.run.app
playform upload my-game.zip --api http://localhost:8080

playform dev [dir]

Run the pack locally without uploading: starts a static server for the pack dir and opens the browser to the web app’s /play/url?manifest=... route.

• [dir] — Pack directory (default: current directory).
• --port <number> — Port for the pack static server (default: 3456).
• --web <url> — Web app URL to open (default: http://localhost:5173).

Requires: The web app must be running (e.g. cd apps/web && npm run dev) so the game runtime can load the pack.

Examples:

playform dev my-game
playform dev my-game --port 3457 --web http://localhost:5173

Install

From repo:

cd packages/cli
npm install
npm run build
npm link
playform --help

From npm (when published):

npm i -g @d3x3/pf-cli
playform --version

Full workflow

1. playform init flappy my-game
2. Edit manifest.json, game.js, and files in assets/
3. playform validate my-game
4. playform pack my-game -o my-game.zip
5. playform upload my-game.zip --api <prod-url>
6. Play at https://playform-0.web.app (Stumble or /play/<gameId>)

See docs/creator-quickstart.md for a copy/paste friendly guide and docs/PRIORITY5-TASKS.md for implementation details.