This reference describes the current CLI. Run gamestage <command> --help for the options in your installed version.
The page lists every gamestage command, what it does and what it leaves behind.
Invocation. This page writes every command as gamestage <command>, the form the shell installer puts on your PATH. From npm, run npx gamestage <command>. From the downloaded bundle, run node gamestage.mjs <command>. gamestage start reports which form it is answering to.
JSON output. --json is a global option and goes before the command: gamestage --json verify. Use it when a script or an agent branches on the result.
Sign-in. Commands marked "Needs sign-in" reach Backstage, so run login first. Sign-in is public and self-serve, so a new account waits for approval. Until a person approves it, dev, verify, manifest register and archive work (up to three games), status lists the games registered so far, and the rest answer access_pending.
Commands
start
Reads the current directory and names the right next step. Run it when you do not know which command to run; it works at every stage of a migration.
It prints its own version, and says when a newer one is out: its only request reads the live pack's version, sends nothing about you, and is skipped quietly offline or when GAMESTAGE_NO_UPDATE_CHECK is set. Read that number first when a command refuses something this page says it accepts. An old cached bundle looks like a documentation error.
doctor
Checks Node, the bundled schema, and whether a manifest is present. Exits 1 when something blocking is wrong, 0 otherwise.
inspect [target]
Reads an existing game and produces an inspection report. target is a game file or a project directory, defaulting to ..
| Option | Meaning |
|---|---|
--write [path] | Write the generated manifest, defaulting to gamestage.yaml |
--force | Replace an existing manifest, losing whatever it holds |
The report also names how the prototype already sits on the screen: screen, canvas, card or page, with the file and line it read that from, and "(possible)" when it is a guess rather than a certainty. --write puts it in the manifest as experience.layout, exactly as create --layout would have. See layout and loading for what each value means.
The inspection is read-only and registers nothing, however many times you run it. Only --write touches the disk, and it refuses to overwrite an existing manifest without --force, because a later manifest may hold a complete container the inspection cannot reconstruct. When the CLI is signed in, --write also registers the manifest it wrote, after writing it, so the id in your gamestage.yaml is the id your workspace holds; a failed registration does not undo the file.
formats [format]
Explains the formats before you choose one: what the fan does, what it suits, what the Engine keeps secret, what a producer writes in Studio, and a deployed game of that format to play. No account needed.
gamestage formats every format you can build, then the ones with no Engine yet
gamestage formats hunt one format in full
gamestage formats trivia a format with no Engine yet, and how to ask for itIf none fits, gamestage suggest "what you want to build" tells us.
create
Starts a new game, choosing its authority before scaffolding anything. Run by hand with no --format or --name, it asks for them, then for who runs the game and their privacy policy for the consent card. An agent, a pipeline or --json is never asked: with no format it prints the menu and exits.
| Option | Meaning |
|---|---|
--name <name> | The game's name |
--format <format> | How the game is played, and so the Engine rules it runs. gamestage formats explains each |
--brand <name> | Who runs the game, named when a fan is asked for consent |
--privacy-url <url> | Your privacy policy's address, linked from the consent card |
--starter <name[@version]> | Start from your organisation's starter app, its newest version in use unless you name one. The game's format must be one the starter app plays. See starter apps |
--no-starter | Start from the format's own page even when your organisation has starter apps |
--here | Write into this folder even when it holds other things |
--host <host> | Where it runs: fullscreen (the default), article-launch, article-embed or app-webview. See layout and loading |
--layout <layout> | How it sits on the screen: screen, canvas, launch, card, page or sheet, defaulting from the host and format |
--write [path] | Manifest path, defaulting to gamestage.yaml |
--force | Replace files that are already there, losing what they hold |
It writes gamestage.yaml, index.html, gamestage.js, gamestage-player.js and favicon.svg, and scaffolds a playable page for hunt, push, group, predict, bingo, shoot and arcade. Three more starters play on hunt: word_guess, a Wordle board, and number_guess, a guess-the-year board (see build a word or number guess game), and phrase_solve, where the fan spins for letters and solves a hidden phrase (see build a solve the phrase game).
Where it writes. Into the current folder when that folder is empty or already holds a page (index.html) or a manifest. Anywhere else, such as a folder holding another project, it makes a folder named after the game and writes there, so your other files are left alone. --here writes into the current folder regardless. --json reports the folder as directory.
It never replaces a file it did not write. A file already in the directory is kept and named in the output, so running create beside a prototype gives you the manifest and the clients while your own page is left alone. A gamestage.yaml that is already there stops the command outright, because that file holds a game and a second one minted beside it would leave the directory with two. --force overrides both.
client
Writes the browser clients into your project in the form a browser can load: gamestage.js, the Gamestage client, and gamestage-player.js, the smaller player API client. Both are regenerated when the command runs again, so keep game logic out of them.
| Option | Meaning |
|---|---|
--out <dir> | Where to write them, defaulting to the current directory |
In an app built with Vite, webpack or another bundler, write them to public/ and load the client from a plain script in the page's head rather than importing it in bundled code, which would copy it into the build where the deploy cannot point it at the hosted client. client prints the line to use; Build and deploy has the rest.
dev
Plays your round through the deployed Gamestage Engine at https://api.gamestage.ai, with your page on your machine. Prints window.GAMESTAGE_API and window.GAMESTAGE_GAME for the page. Needs sign-in, a registered game and a network connection. There is no watch mode: stop and restart after changing the manifest or the practice round.
| Option | Meaning |
|---|---|
--port <port> | Local HTTP port for the page's calls, default 4000 |
--manifest <path> | The game's manifest, default gamestage.yaml |
--serve | Also serve this directory, so the page has somewhere to open |
--serve-port <port> | Port for the page with --serve, default 4001 |
dev plays practice/round.yaml, beside the manifest, when there is one, and otherwise a stand-in round for the game's format, the same one review plays. It names which in one line: "Round: practice/round.yaml (practice only, fans never see it)" or "Round: stand-in round". The round goes onto the Engine under the game's own practice slot, so it never replaces the round fans are playing. Every play is a test play: marked by the real Engine and kept off every leaderboard. With --serve, a page playing a practice round shows a "Practice round, not live" bar, added by dev and never by the client, so a deployed game cannot show it. A deploy never uploads practice/. A game's real rounds are written in Studio.
An arcade game has no round, so dev plays it differently. It answers the page's calls with a stand-in for the Arcade Engine on your machine, which needs no sign-in and no network. Each run is timed on that stand-in's clock and checked against your limits under backend.arcade in gamestage.yaml, the same checks the live Arcade Engine makes. The terminal prints each run's score, your best and your place. A run that breaks a limit is refused and does not count, as on the live Engine, and the terminal names every limit it broke, such as "points_per_second: 5000 points in 0.1s is more than the 0 that 10 a second allows". Runs and the board stay in memory and go when dev stops. With --serve, the page shows a "Local practice, not live" bar. verify plays one run against the same stand-in for its browser checks.
When it fails:
| What it says | What to do |
|---|---|
| "Cannot reach the Gamestage Engine" | Check your connection and run it again. Nothing about your game is wrong |
| "… is not registered to your workspace" | Run gamestage manifest register, then dev again. create registers a new game for you |
| "You are not signed in" | Run gamestage login |
--fixture, --scenario and --as were retired when dev moved to the deployed Engine, and each now says why. To prove sign-in, deploy the game with its own identity.jwt issuer and play the deployed page.
look [url]
Opens a page in Chrome at phone size, presses what you name, and saves what is on screen. Built for a coding agent as much as a person: with dev --serve running in the background, an agent runs look, opens the screenshot as an image, and sees the game it is building, the way you would check it by eye.
gamestage look --tap "Play" --tap "Take the shot"It prints the screenshot's path, each press and whether anything matched it, whether the page scrolls sideways, every console error and uncaught exception, and the words in the window, top to bottom. With --json it prints the same as one object. It never edits a file; the screenshot is the only thing it writes.
| Option | Meaning |
|---|---|
[url] | The page, default http://127.0.0.1:4001, the one dev --serve serves |
--tap <target> | Press a button or link by its words, label or test id, or by a CSS selector. Repeat to press several, in order. A button wins over a section that happens to contain the same words |
--width <px>, --height <px> | The screen, default 390 by 844 |
--out <file> | Where the screenshot goes, default .gamestage/look.png |
--wait <ms> | How long to let the page settle after loading and after each press, default 1500 |
If nothing answers at the address it says so and names dev --serve. If Chrome cannot start it says so and stops: set GAMESTAGE_CHROME to a working Chrome, Chromium, Brave or Edge. A press that matches nothing is reported and skipped, never guessed at.
verify
Runs checks on the migration, including play against the deployed Engine. Needs sign-in and, for the browser checks, a network connection. It runs a set of checks: whether the round played here is this game's own, whether the attempt cap was chosen rather than defaulted, whether scanned files in the publish set contain known answers, whether every producer setting the page offers is read by the game, whether a generated client is present and the game reaches Monterosa through it rather than around it, whether a deadline comes from the server's clock, and, when a browser is available, whether the screen shows what the server decided and notices the connection going and coming back.
The first check walks the publish set rather than the named page, using the same call deploy --dir uploads with, so a manifest, data file or source map holding the answers beside a clean page is a fault rather than an oversight. Files are read on their contents rather than their extension; binaries and very large files are listed but not opened, so verify does not inspect them for leaked answers. A passing result covers the checks it ran, not every possible leak or cheat. Assurance records are what the creator recorded, not checks Monterosa made.
| Option | Meaning |
|---|---|
--file <path> | The game to verify, normally index.html |
--manifest <path> | The game's manifest, default gamestage.yaml. The round is practice/round.yaml beside it, or a stand-in |
--dir <path> | The directory a deploy would publish, default the game's own |
--no-browser | Skip the browser proof |
--no-minify | Play the page as written. By default the browser plays the minified copy a deploy would publish |
The browser checks play the round on the deployed Engine, the way dev does, as test plays. If the Engine cannot be reached, verify says so, marks those checks skipped and exits 2, never 1: an outage is not a broken game, and a check it could not run is never counted as passed. Exit 0 means verified, 1 means a check is open, 2 means something could not be proved here.
Use it in CI
Pin the CLI version for reproducible builds: set it once, to the version you last tested with, and raise it on purpose. Check both the process exit code and the JSON ok field: 0 means the command did what it said, or there was nothing to do; 1 means it was refused or failed, so do not treat the change as made; 2 means verify could not prove something here. prune can exit 1 after removing some records: its JSON carries removed and refused counts. This example validates the manifest without a browser:
GAMESTAGE_VERSION=0.53.0
cli_status=0
npx "gamestage@${GAMESTAGE_VERSION}" --json manifest validate gamestage.yaml > validation.json || cli_status=$?
if [ "$cli_status" -ne 0 ]; then
cat validation.json
exit "$cli_status"
fi
node -e 'const fs = require("node:fs"); const result = JSON.parse(fs.readFileSync("validation.json", "utf8")); if (result.ok !== true) process.exit(1);'Manifest validation checks the declaration, not gameplay or leaked answers.
review
Plays the built game against the deployed Engine, in a headless browser at phone size, and gives advice on whether fans will come back. Run it from the game's folder before deploy:
npx gamestage@latest review --file dist/index.htmlPlaying the game needs sign-in; signed out, review still gives the advice that reads the files and marks the play skipped. Every line is ok, advice (with the rule and a fix) or skipped (with why). It never fails and always exits 0: these are judgements, not faults. The rules and the research behind them are in Design a game fans come back to.
| Check | What it looks at |
|---|---|
| First answer | Seconds and taps from arriving to the first answer, against 30 seconds and 3 taps |
| Play next | Whether Play next (or a greyed Come back tomorrow) is the main button after a round |
| Story | Whether the story opens on its own, whether it runs past 3 slides, and whether a story button opens anything. Found by what it does: a full-screen layer with a row of progress segments, whether it is Gamestage UI's Story or the game's own |
| Come back | Whether the result screen shows a streak or when the next round opens |
| Share | Whether the page declares a share card and offers a Share button |
| Ties | How many distinct scores a round can award, from its scoring rules |
| Options | Six options for a one-answer pick |
| Rounds | Rounds ready in the live pool, when you are signed in and the game is deployed |
A game whose rounds live in Studio has no round in its manifest, so the tie estimate uses a representative round of its format and says so. The game's own gamestage.settings.json stands in for Studio, as it does for dev --serve.
| Option | Meaning |
|---|---|
--file <path> | The game's page, default index.html |
--manifest <path> | The manifest, default gamestage.yaml |
Set GAMESTAGE_REVIEW_SCREENSHOT=/tmp/result.png to save the result screen as it was reviewed, to check the advice by eye.
suggest [what]
Tells us about a format or feature that does not exist. No account needed, and the right moment is the one where you ran out of road.
Put a long multi-line report in a file. POSIX shells preserve newlines inside quoted arguments. A file is easier to review: this command reads standard input, so redirect the file as below. For a command with a file flag, use that flag, or keep the argument on one line.
gamestage suggest --send < suggestion.txtThe argument still works and is still the shortest way to send one line.
Without --send it prints the exact payload and sends nothing. That payload is four strings: what you were building, the format that came nearest, the CLI version, and a marker saying it is a suggestion. Never the game. No manifest, no round, no answers, no source, and there is nowhere in the shape to put one.
| Option | Meaning |
|---|---|
--closest <format> | The format that came nearest, if one did |
--send | Send it, having seen what it says |
issue [what]
Reports something that went wrong. No account needed, and it lands in the same backlog a suggestion does, titled so a bug is not read as a wish.
Put a long multi-line report in a file, then redirect it to standard input as below, or keep the argument on one line. A newline inside a quoted argument does not end a command in a POSIX shell.
gamestage issue --send < report.txt
type report.txt | gamestage issue --send # WindowsThe argument still works and is still the shortest way to send one line. Nothing here opens a file of its own: the pipe carries what you chose to put in it, and --game is an id you type rather than a file the command reads.
Without --send it prints the exact payload and sends nothing. That payload is six strings: what went wrong, the game you named, the CLI version, the node version, the operating system, and a marker saying it is a bug report. Never the game. No manifest, no round, no answers, no source, no file paths, and there is nowhere in the shape to put one. --game is the id you type, not a file the command reads.
| Option | Meaning |
|---|---|
--game <id> | The game it happened on, if it was about one |
--send | Send it, having seen what it says |
manifest validate [path]
Validates a manifest and reports the build stage its evidence supports. Path defaults to gamestage.yaml. --level <level> requires a conformance level from L0 to L5 and exits 1 when the manifest does not reach it.
manifest register [path]
Registers an existing manifest with Backstage. Safe to repeat, and needed when a manifest was created while signed out. Needs sign-in.
live on, live off
Switches live data on or off for the game in this folder by adding or removing the live: section of gamestage.yaml, and leaves the rest of the file, comments included, as it was. With no subcommand it says which it is. --provider <name> picks where the contest comes from (sportmonks today) and --manifest <path> points at a manifest elsewhere. Neither reaches anybody until the next deploy. See Live data.
live simulate, live list, live pause <id>, live play <id>, live stop <id>
Plays a made-up contest on the deployed live feed, so a deployed game can be rehearsed with no contest on. simulate prints an id such as sim-4f2a91c0; put it in the edition's Live contest in Studio and every game on that edition follows it within a minute. --speed <n> is contest seconds per real second (30 by default, 1 to run like a real contest), --seed <n> picks the contest, and --from <minute> starts it part-way through. list shows each of the workspace's simulations with its state, minute, score and speed. pause holds it for everyone following it, play carries on from where it was, and stop ends it at full time with the score it had. Three at once per workspace, each for up to 24 hours. Needs an approved account with live data open to it. See Live data.
login, logout, whoami
login signs in, and creates an account when none exists: there is no separate signup and no website step first. It starts a WorkOS device flow, so a person has to approve it in a browser. logout forgets the stored session. whoami prints who the CLI is signed in as.
| Option | Meaning |
|---|---|
--workspace <id> | The workspace you expect to land in, from the welcome screen |
link github
Links your GitHub account through a second device flow, which a first deploy requires. Needs sign-in.
open <game> [where]
Opens the game in the browser. where is play (the default: the game as a fan plays it), studio (its Studio project, where rounds and words are written) or stage (its page on gamestage.ai). With --json, or on a machine with no browser, it prints the address instead. A game not yet deployed has no Studio project, and the command says so.
docs [chapter]
Prints a chapter of this documentation in the terminal, fetched from gamestage.ai so it is never out of date. With no chapter it lists them. gamestage docs game-formats and gamestage docs cli are the two most used; formats, deploy and manifest work as short names. No account needed.
A newer version
The CLI checks npm at most once a day, with a short timeout, and the check never slows or fails a command. It never checks in CI or with GAMESTAGE_NO_UPDATE_CHECK=1.
After a command you run by hand, when a newer gamestage is out, it prints one line saying so and how to update.
With --json, the answer carries the same news instead, as a top-level update field, so an agent hears it too:
"update": { "latest": "0.39.0", "current": "0.38.0", "command": "npx gamestage@latest" }The field is absent when this CLI is current. An agent should tell you in one line and run npx gamestage@latest from then on.
Update required
Every call the CLI makes to Gamestage carries its version. When Gamestage needs a newer CLI than the one you ran, the command stops, exits 1, and prints one line:
Update required: this is gamestage 0.38.0, and 0.39.0 or later is needed. Run npx gamestage@latest.With --json it is an error object with "code": "update_required" and the same sentence. Nothing was changed. Run the command again with npx gamestage@latest and it goes through.
A deploy can also stop because the folder is ahead of the CLI: its gamestage.js came from a newer Gamestage client than this CLI carries. The deploy says so, and the fix is the same:
This folder uses Gamestage client 0.77.0, newer than this CLI knows (0.76.0). Update with npx gamestage@latest, then deploy again.status [game]
gamestage list is the same command: with no game named, it lists your games.
What is deployed, what state it is in and which limits are near. One game when named, the whole workspace when not. Needs sign-in.
Name a game and it also says whether that game is serving as dev or prod, read with effectiveStage rather than inferred from promote having succeeded. On dev it names which of the two gates is still shut: your own approval (gamestage promote), your workspace's plan, or both. An archived game is told neither, because it serves nobody and promote would refuse it.
The workspace list does not repeat that per row. Every row would carry the same sentence, and a game's state and its serving stage are different questions, so "live, dev" side by side reads as a contradiction rather than as two answers. --json does carry it for every game, because an agent branches on a field rather than reading a column.
rename <game> "<new name>"
gamestage rename derby-day-7f3a "Derby Day"Gives a game a new name and keeps its id. The id is in every address, so links to the game keep working. Needs sign-in and an approved account; the workspace's owner and its members can both rename a game.
The new name shows in Stage, gamestage status and the game's log at once. In Studio, the game's project takes the new name, and so does its Display name setting while it is empty or still says the old name. A Display name a producer changed is kept. A game that has not deployed has no Studio project yet, and its first deploy creates one.
Change app.title in gamestage.yaml to the new name too. A deploy renames a game only when that title changes, so a deploy of a folder that still says the old name keeps the new one. A game's first deploy takes its name from the title, so for a game that has never deployed, change the file before you deploy. The command checks the folder it runs in, or --dir <path>, and says when the file still has the old name, and whether deploying that folder would rename the game back.
| Option | Type | Default | What it does |
|---|---|---|---|
<game> | id | required | The game to rename. Its id never changes. |
<name> | text | required | The new name, in quotes. Spaces at either end are trimmed. |
--dir <path> | path | . | The game's folder, checked for a gamestage.yaml that still has the old name. |
With gamestage --json rename, the answer is { ok, game, name, previous, studio }, where studio is updated, kept, none or failed.
When it refuses, it says why and exits 1:
| Refusal | What to do |
|---|---|
| The name is empty | Put the new name in quotes. |
| The game is archived | Nothing: an archived game is off the air. |
| No game with that id | Run gamestage status for your games' ids. |
Renaming a game to the name it already has changes nothing and exits 0. If Studio could not be reached the first time, running the same rename again retries the Studio project and its Display name. A deploy renames the project but never moves a Display name that already holds a value.
deploy <game>
Publishes a snapshot to a Playground, and the round it puts on. Needs sign-in.
Run it from the game's folder with --dir .. Without --dir or --file no files are uploaded: a redeploy keeps the page already live, and a first deploy is refused until a page is published.
| Option | Meaning |
|---|---|
--file <path> | The game's HTML, uploaded before the deploy gate runs |
--dir <path> | The game's directory, uploaded with relative paths |
--manifest <path> | Manifest the round is read from |
--revision <revision> | Manifest revision being published |
--hash <hash> | Content hash of the snapshot |
--level <level> | Evidenced conformance level, L0 to L5 |
--prize | The game offers a prize, which is a paid plan only |
--notes <text> | What changed, said in the deploy announcement and in logs |
--space <id> | The Studio space to put this game's project in. Default: your organisation's, then the configured default |
--space-org <id> | The Studio organisation --space belongs to, when it is known |
--no-check | Skip loading the published page in a browser afterwards |
--no-minify | Publish the game's scripts, styles and pages as written, comments and all |
--allow <path...> | Publish a file the deploy gate suspects; never clears a certain finding |
--dir uploads everything under the directory, withholding the manifest (gamestage.yaml or .yml), environment files (.env, .env.local, .env.*) and the downloaded CLI (gamestage.mjs, cli.mjs), and removes stale files an older deploy left. Your editor's and coding agent's files are left out and named in the output: every folder whose name starts with a dot, such as .agents/, .claude/, .cursor/ and .vscode/, plus AGENTS.md, CLAUDE.md, GEMINI.md and skills-lock.json. verify leaves them out too. .git/, .next/ and node_modules/ are walked past and named as before. The generated clients, gamestage.js and gamestage-player.js, are walked but not uploaded either: whatever imports them has that import rewritten to the hosted client at a pinned version instead. Upload happens before the deployment gate, so a refused deploy can leave new files in storage without making the game live. The picture that stands for the game in Stage comes from its format and is there from registration, so a deploy has nothing to run and nobody has a brief to write.
A deploy publishes a smaller copy of your own files. Each .js, .mjs and .css file, and the inline <script> and <style> blocks and comments in each page, is minified on its own: whitespace and comments go, names stay as you wrote them, nothing is bundled or renamed. Licence comments (/*!, @license) stay. Files already minified (.min.js, a build's hashed assets/ files, or anything mostly on very long lines), data, SVG and page text are published as they are. Your folder is never changed, and every check reads it as written. No source map is published. A file the minifier cannot read is published as written and named in the output. --no-minify turns it off for one deploy.
A first deploy needs no round. It puts the game online and creates its project in Studio, which is where its rounds are then written. With no round yet, deploy says so, No round yet: add one in Studio, with the link to the game's Studio project, and skips the browser check, because a page with nothing on is not a broken page. The round appears without another deploy once a producer writes it.
reference push <name> <file>
Uploads the private values a round is scored against. name is what a producer types in Studio, such as the-limit/careers.json, and file is the JSON file holding it. Needs sign-in.
The file is read and validated on your machine before anything leaves it, because the server never sees the bytes: they go to a private prefix from a signed URL. One push writes two objects, the pointer at the name a producer uses and a copy keyed by the digest of those exact bytes. A round records the digest it was provisioned against, so asking what a round was scored on is a lookup rather than an argument.
A round provisioned after the push uses the new values. A round already being played keeps the values it opened with, because a fan's page load will not re-value a round underneath them, and the change goes on at the next deploy or explicit refresh. Dataset has the file's shape and what must never go in it.
| Option | Meaning |
|---|---|
--drop-scoring | Push anyway, when the file would remove a measure's scoring block that a live round depends on |
--kind <kind> | data (the default), or media to catalogue pictures and video from a CSV into your Studio Space's asset library |
With --kind media, file is a CSV of key,label,url,tags,rights,source_id,alt and each row's picture or video is put in your workspace's own Studio Space asset library, named and tagged, with its rights kept beside it. Every row is checked first and each refusal is named by row; the good rows still go in, and the command exits 1 if any row was refused. Catalogue images and video has the columns and every refusal.
npx gamestage reference push club-archive catalogue.csv --kind mediaWithout --drop-scoring, a push that would stop a measure scoring rounds is refused and names the measure: see Scoring a push round by how close it came.
reference check <file-or-name> [keys...]
Reports what a round would fail on, before a producer finds out by having one refused. Given a media catalogue's name rather than a file, it shows what each key became in Studio (asset, tags, rights, source id and address) and names any key the catalogue does not hold; that form needs sign-in. It prints how many values each measure holds, and when you name keys it says which of them are absent.
A key the dataset does not hold is left out of its group rather than scored as nothing, so a typo quietly removes that player from the round, and a group left with no real choice refuses the round. This is that same check, run against the file, by the person who can fix it. It names a missing key and never prints what a present one is worth. Nothing leaves the machine and no account is needed.
reference inspect <source>
Shows what a file or an API holds, and which of its fields could become a dataset. source is a JSON or CSV file, or an https:// address that returns one. Nothing leaves your machine except the request to that address, and no account is needed.
npx gamestage reference inspect players.json
npx gamestage reference inspect https://api.example.com/v1/players --header "Authorization: Bearer $KEY"For a Gamestage dataset, it lists each measure with how many values it holds and their range, and says the file is ready to push. For anything else, it finds every list of records inside it, describes the fields of the biggest one, and suggests three things:
| Suggestion | What it is |
|---|---|
| Key | A field on every record and different on each, such as a player id. A round's entries use these keys |
| Name | A text field a producer reads when choosing entries, such as a player's name |
| Measures | Fields holding numbers, including numbers sent as text. A field with negative numbers is named and left out, because a dataset cannot hold them yet |
It ends with the reference build command that would turn the list into a dataset. Values appear in the output because the data is yours.
| Option | Meaning |
|---|---|
--header "Name: value" | Sent with an address, for an API that wants a key. Repeat for more. Never printed |
reference build <source>
Turns a file's or an API's records into a dataset you can push. Use the key, name and measures reference inspect suggested. No account is needed.
npx gamestage reference build players.json --key id --measure goals --measure assists --label name --out dataset.jsonA measure with decimals is stored as whole numbers with a scale, so 7.5 becomes 75 with a scale of 10, and a round shows it as 7.5 again. The command refuses, and names the field, when a key appears on two records or a measure holds a negative number. It reports how many records had no value for each measure.
| Option | Meaning |
|---|---|
--key <field> | Required. The field that names each entry |
--measure <field> | Required. A field holding the numbers a round counts. Repeat for more |
--label <field> | The field holding a name a producer reads |
--list <path> | Which list of records, as reference inspect shows it, such as $.elements. The biggest by default |
--source <text> | One line saying where the data came from, shown when a round reveals it |
--header "Name: value" | Sent with an address. Repeat for more |
--out <file> | Required. Where to write the dataset |
--force | Replace the --out file if it exists |
reference list
Lists every dataset your workspace holds: where it came from, how many entries and measures it has, its size, when it was published and which games read it. It never prints a value. Needs an approved account.
npx gamestage reference listreference status <name>
Shows one dataset in full: where it came from, its digest, each measure with how many entries it holds and whether it scores rounds, the games that read it and whether any is on an older copy, and the rounds built from it. For a media catalogue it shows the Studio Space, how many items and of which types, and each item with its rights. A name your workspace does not hold is refused with the names it does. Needs an approved account.
npx gamestage reference status wages/pl.jsonreference download <name> [file]
Gets back a dataset you uploaded, byte for byte, so you can check what rounds are scored against or edit it and push it again. Writes to file, or to the dataset's own file name in the current folder. Needs an approved account.
npx gamestage reference download wages/pl.jsonOnly data you uploaded can be downloaded. A dataset Gamestage pulls from a source for you is licensed for scoring games, not for taking away, so it is refused. Every download is recorded in your workspace's audit trail.
| Option | Meaning |
|---|---|
--force | Replace the file if it exists |
reference run <name>
Pulls a dataset a source fetches for you now, rather than waiting for its schedule, and says what landed: how many entries, which measures, the first few keys and the digest. It never prints a value. Use it after sources connect to check the source works. Needs an approved account.
npx gamestage reference run fpl/almanac.jsonPulled fpl/almanac.json: no change
Digest 82c7633c4497a79d
Entries 669 entries
Measures player_price, season_points, points_per_game, minutes, starts, goals, and 22 more
First keys 1, 2, 3, 4, 5
Requests 1A pull costs the supplier requests, so a dataset can be pulled this way once every 15 minutes. A large source can take a few minutes; the command waits and says so. Exits 1 when nothing landed.
| Answer | What it means |
|---|---|
new figures | The supplier's numbers changed. Rounds built from now on use them; rounds already open keep theirs |
no change | The numbers match what was already published, so nothing was rewritten |
| Refused, with the supplier's reason | Nothing was written. The data you had stays, and games keep using it |
No source pulls <name> | You pushed this dataset yourself. Push a new file to change it |
| Pulled under 15 minutes ago | Ask again after the time it gives |
| The pull landed no entries | A round built from it would have nothing to score. Exits 1 |
| Option | Meaning |
|---|---|
--no-wait | Ask for the pull and return at once. reference status <name> shows when it lands |
reference delete <name>
Removes a dataset no game reads. Asks you to type its name first. Needs an approved account.
npx gamestage reference delete old/unused.json| Refused when | What to do |
|---|---|
| A game that is not archived reads it | Point the game at another dataset in Studio, or archive it, then delete |
| A source pulls it on a schedule | Switch the source off with gamestage sources disconnect <source> |
There is no terminal to ask and no --yes | Pass --yes if you mean it |
No new round can be built from a deleted dataset. Rounds already open keep the numbers they opened with. The removal is recorded in your workspace's audit trail, and Monterosa can recover the file if you delete one by mistake.
| Option | Meaning |
|---|---|
--yes | Remove it without asking |
sources
Lists where a game's real-world values can come from, and which of them your workspace can use now. Needs an approved account.
npx gamestage sourcesFor each source it prints what it offers, what it covers, what it costs, and the licence position, then its state for you: connected (data from it is already in your workspace), available, available, needs a key (sign up with the provider, then connect your key through the page it gives you), or not available to you, with the reason. --json prints the same for an agent.
Run it before designing a game that needs real figures. It never asks for a key, and you should never paste one into a chat: a key goes in through a Gamestage page.
sources connect <source>
Prints the Stage page where you add your own key for a source, such as sportmonks. Needs an approved account for the page itself.
npx gamestage sources connect sportmonksOpen the link in your browser and paste the key there. Gamestage checks it with the provider once, then stores it in AWS Secrets Manager for your workspace and uses it only to fetch your data on a schedule. The command never takes the key, not as an option and not as input, so a coding agent running it never sees it. A wrong key is refused on the page with the reason, and nothing is stored.
A Mystery game needs a TypeSafe key. Jev, the AI judge that answers fans' questions in a Mystery game, runs on your workspace's own TypeSafe key, so each question is charged to your TypeSafe account. Connect it the same way:
npx gamestage sources connect typesafeGamestage checks a TypeSafe key with one yes-or-no question to Jev, which costs about a millionth of a dollar. Until a key is connected, your Mystery games tell fans they cannot answer questions right now, and gamestage deploy and gamestage promote say so each time they run. gamestage usage <game> shows what the questions have cost.
At your own terminal, from 1Password. If you cannot use the page, you can read the key from your own 1Password instead:
npx gamestage sources connect sportmonks --from-op "op://Private/Sportmonks/credential"| Option | Meaning |
|---|---|
--from-op <reference> | A 1Password secret reference, op://vault/item/field. The CLI runs op read itself and sends the key straight to Gamestage |
It needs the 1Password CLI, signed in, and 1Password asks you to approve the read. The key is never printed, logged or written to disk: you see "Connected", its last four characters, and the competitions your plan covers. There is no way to pass a key itself, as an option, on input or in an environment variable. This route is for a person at their own terminal: a coding agent must never run it or write the reference for you. Every attempt to connect a key, by either route, is recorded against your workspace without the key, and five attempts an hour is the limit.
Fantasy Premier League, no key. connect fpl switches FPL on for your workspace and pulls every Premier League player into a dataset called fpl-premier-league, twice a day. It takes --measures and --name as ESPN does below, and no league or season. sources status fpl --measures lists its measures.
npx gamestage sources connect fplESPN, no key. ESPN's public statistics need no key, so connect switches the source on for one league and pulls its season into a dataset:
npx gamestage sources status espn --league nba
npx gamestage sources connect espn --league nba --measures offensive_points,general_rebounds| Option | Meaning |
|---|---|
--league <league> | Required for ESPN: nba, wnba, nfl, mlb or nhl |
--measures <keys> | Comma-separated measures to pull, named by group, such as offensive_points. sources status espn --league <league> lists them. Default: the league's four usual measures |
--season <year> | ESPN's year for the season, such as 2025. Default: the current one |
--name <dataset> | The dataset's name. Default: espn-<league> |
sources status <source>
Says whether your key for a source is connected, when it was connected, and which competitions your plan covers. It never shows the key. For ESPN, --league <league> lists the measures that league offers; for FPL, --measures lists its measures. Needs an approved account.
npx gamestage sources status sportmonks
npx gamestage sources status espn --league nbasources disconnect <source>
Removes your key for a source. Its scheduled pulls stop at once; data already in your workspace stays. Connect again with sources connect. For ESPN, --name <dataset> says which dataset, such as espn-nba. Needs an approved account.
npx gamestage sources disconnect sportmonks
npx gamestage sources disconnect espn --name espn-nbaround push <game>
Writes practice/round.yaml into Studio, where a producer owns it from then on, and prints the link to the game's Studio project. It is the only way a round goes from your machine into Studio. Needs sign-in.
| Option | Meaning |
|---|---|
--manifest <path> | The game's manifest, default gamestage.yaml. The round is read from practice/round.yaml beside it |
--yes | Do not ask before replacing what a producer has typed, default off |
It prints what is about to go in, then asks. Without a terminal and without --yes it refuses and writes nothing, because it replaces what a producer typed and nobody was there to be asked. That refusal comes before it reaches the control plane, so an unattended run is turned away whether or not the CLI is signed in.
What travels differs by format. A push round sends only its public half: an entry's point value would be broadcast to every connected browser, so the values stay in your dataset where only the Engine reads them. A hunt or group round sends its answer too, into a field Studio withholds from a fan's browser. A predict round is refused by name, because a prediction's question and options are the platform's own and are authored in Studio itself. A shoot round sends its settings; the keeper is the Engine's and never travels.
There is a push and there is no pull. Once the round is in Studio a producer's edits live there, and a pull would put them back into a manifest, which is the one thing a manifest must not hold. status <game> reports the round a game is serving without writing anything.
round season <game>
Writes a season of rounds into Studio, one edition a day. Each day is an edition named for its date, running from midnight to midnight in the file's time zone, with that day's round on it. The platform's current edition is today's, so the game plays each day's round on its day. Needs sign-in and a game that has been deployed once.
gamestage round season grid-guess --dry-run
gamestage round season grid-guess --yes| Option | Meaning |
|---|---|
--file <path> | The season, default practice/season.yaml |
--manifest <path> | The game's manifest, for its format, default gamestage.yaml |
--overwrite | Write over days that already have a round in Studio, default off |
--dry-run | Check the file and say what would be written, without writing |
--yes | Do not ask before writing, default off |
The file is a timezone (default Europe/London) and a list of days. Each day is a date, such as 2026-11-01, plus a round as practice/round.yaml holds it. The whole file is checked before anything is written, and every problem is reported by date, such as a date written twice or a phrase with no letters.
Write a week of quiz questions
A quiz game's day is its questions rather than a round. Each day becomes an edition named for its date, with one question on it per entry, in the order the file lists them. answer is the right answer's letter, a for the first, and is never sent to a fan. closesAt is when the quiz stops taking answers; leave it out and the quiz stays open. source is optional: it says where the answer came from, and is saved as a note on the question in Studio so anybody can check it.
timezone: America/New_York
days:
- date: 2026-11-18
closesAt: 2026-11-18T23:00:00-05:00
questions:
- question: Who scores more points per game, Luka Doncic or Jalen Brunson?
options: [Luka Doncic, Jalen Brunson]
answer: a
points: 10
source: ESPN leaders, 17 Nov, 33.1 against 26.4| Field | Type | Required | What it does |
|---|---|---|---|
question | text | yes | The words a fan reads |
options | list of 2 to 6 | yes | The answers, in the order a fan sees them |
answer | a to f | yes | The right answer. Refused if it names a letter past the last option |
points | 0 to 1000 | no | What a right answer scores. Empty means the quiz's default |
source | text | no | Where the answer came from, kept as a note in Studio |
closesAt | date and time with time zone | no | Set on the day, not the question: when the quiz stops taking answers |
A day holds at most 50 questions. With --overwrite, a day ends up holding exactly the file: its questions are rewritten in order, and any extra question already on it is deleted.
Running it again is safe. A day that already has a round in Studio is kept, because a producer may have edited it since, so adding days to the file and running it again writes only the new ones. --overwrite writes over every day in the file instead, and asks first.
Two editions never run at once. A game that plays the current edition stops if two are running, because it cannot tell which is today's. So a day starts at its midnight or when another edition overlapping it ends, whichever is later, and the command prints the start time of any day that moved. A day already over is skipped, and one that another edition covers entirely is refused with what to do. The command exits 1 if any day was not written.
round fill <game>
Fills a quiz game's day from the question templates a producer wrote in Studio and the day's NBA games and statistics, then writes it as round season writes a quiz day. No AI writes a question: the words are the producer's template, the names come from the day's games, and each right answer is a figure read from the data. Needs sign-in, a quiz game that has been deployed once, and at least one template.
gamestage round fill trivia-tonight --dry-run
gamestage round fill trivia-tonight --date 2026-11-18 --yes| Option | Meaning |
|---|---|
--date <date> | The day to fill, default tomorrow in the league's time zone (New York for the NBA) |
--league <league> | Whose games and statistics, default nba, the only league for now |
--overwrite | Write over the day if it already has questions, default off |
--dry-run | Show the filled questions, their right answers and sources, without writing |
--yes | Do not ask before writing, default off |
The data is ESPN's, which is unofficial, so a filled quiz is for development and demos. A customer's quiz needs a licensed feed.
Write a question template
In Studio, open the game's project settings and add an item under Question templates. Each item fills one kind of question:
| Box | Required | Example | What it does |
|---|---|---|---|
| Wording | yes | Who scores more points per game, {A} or {B}? | What fans read. {A} and {B} are replaced with the two names |
| Picks from | no | Players in the day's games | Players or teams. Empty means players |
| Mix games | no | Off | Off: the two come from opposite sides of one game. On: from any two of the day's teams |
| Stat | yes | Points per game | The figure that decides the answer. Wins is for teams only |
| Right answer | no | The higher figure | The higher or the lower figure. Empty means higher |
| Points | no | 10 | What a right answer scores. Empty means the quiz's default |
| Questions a day | no | 2 | How many questions this template fills each day. Empty means one |
Players come from the season leaders for the stat, so a player outside the leaders is never asked about. Two figures are only asked about when the larger is at least 1.2 times the smaller, so a fan is never marked wrong on a rounding difference. The same two names are never asked about twice in one day, and a re-run for the same day fills the same questions.
When a template cannot be filled, it is named and left out, never filled with a blank: for example, no two players on opposite sides of one game separate clearly on that stat. A day with no games writes nothing and says so. The command exits 1 when nothing was written.
round seed <game> --count <n>
Builds candidate rounds from the game's connected dataset and writes them to Studio. Needs sign-in and a game that has been deployed with a dataset connected. A round with content is never overwritten; a producer reviews and publishes the new rounds in Studio, where each is named and annotated like every other round. This does not publish them or refresh the Engine.
Where each round goes depends on how the game chooses its live round ("How the live round is chosen" in Studio):
| Game | Where the rounds go |
|---|---|
| Calendar, the default: one round a day | Today's round if the deploy left it empty, then any later edition with no round, then a new edition per round, each starting when the last ends and as long as today's |
| Rotation: a pool chosen by the clock | Beside the existing rounds in the current edition |
On a Calendar game, an edition that already holds two rounds is refused by name rather than added to. Remove one in Studio and run it again.
--dataset takes any of your dataset names, such as fpl-premier-league, in place of the one the game names.
gamestage round seed points --count 5 --measure season_points --dry-run
gamestage round seed points --count 5 --measure season_points --yes
gamestage round seed almanac --count 3 --measure assists --position Goalkeeper --dry-run| Option | Meaning |
|---|---|
--count <n> | Required, 1–80 distinct rounds |
--measure <key> | Dataset column; required when the dataset has several measures |
--position <position> | Exact position filter, ignoring case |
--team <team> | Exact team filter, ignoring case |
--layout <layout> | grid (cards, the default), pitch (players on a football pitch) or xi (Complete the XI, built from a line-up dataset) |
--dataset <name> | Read this dataset of yours instead of the game's own, such as sportmonks/premier-league-lineups.json |
--prompt <text> | The question for xi rounds, with {position} and {team} filled in from each round |
--dry-run | Print complete candidate rounds as JSON, without writing files or Studio elements |
--yes | Create the rounds without the interactive consent prompt |
Dry-run is explicit, including when stdout is redirected. This follows the CLI's existing convention: a non-interactive stdin requires --yes to write, while --dry-run needs no consent. Dry-run still reads the connected dataset through the authenticated control plane. The private dataset stays on the server.
For push, each position gets a slate of up to four entries (at least two, at most eight positions). The target has one to five exact squads, counting all combinations of one pick per slate, including different picks with equal values. Values never go onto the element; the selected measure and target do.
For computed hunt, each board has four distinct players and asks for the highest figure. “Clearly separates” means the answer is strictly greater than the runner-up and at least 1.5 times its figure. A positive answer against three zeroes qualifies; an all-zero board or a tie for highest never does. The element carries dataset keys and the highest-value rule, so the Engine recomputes the answer during provisioning. Dataset changes can invalidate an old candidate's separation; the preview describes the data read at that time.
Filters run before selection. Missing names, missing push positions, insufficient entries or ambiguous measures produce an explanation. Selection is reproducible for the same dataset and options. Search stops after 5,000 candidate attempts; if it cannot fill the requested batch, nothing is written. Reduce --count or widen the filters. Re-running a successful seed creates additional elements. An edition's 80-element limit still applies, including existing elements. If a write fails partway through, the command reports how many were created; inspect Studio before retrying. The control plane must include this command's candidate endpoint and additive round-writing support.
round refresh <game>
Reads Studio and the dataset again now and provisions what it finds, rather than waiting for the next fan's visit. Needs sign-in.
It changes nothing a producer wrote: it re-reads and re-provisions exactly as a fan's visit past the cooldown would, and prints the last lines the game logged so you see what it did. Use it after pushing a new dataset with reference push, or when a producer's edit should reach fans before anyone opens the game.
round reveal <game>
Reveals the answer to a prediction question, the same as Set answer on the game's Results tab in Stage. Needs sign-in.
gamestage round reveal saturday-predictor-3f2a
gamestage round reveal saturday-predictor-3f2a --question el_7d1c --option ArsenalWithout --option it lists each edition's questions, their options by number and the answer Studio holds now. With it, it saves the answer in Studio as the question's right option, and fan scores are updated from it. Setting a different answer later corrects the scores, and a fan who asked to be told their result is sent a correction.
| Flag | Value | Default | What it does |
|---|---|---|---|
--question <id> | question id | the game's one question with options | The question to answer, by the id the list prints. Needed when the game has more than one. |
--option <n or label> | option number or label | none: lists the questions | The right option. A label matches ignoring case. |
--edition <id> | edition id | the one edition holding the question | Needed only when the same question id is in more than one edition. |
Only a question with options can be revealed here. A scoreline or number question's result is set on its Result tab in Studio, and the command says so rather than sending it. An option that is not on the question is refused with the list of options, and an answer that is already set changes nothing.
fixtures
Lists the sports, leagues and matches a predict game can be revealed from automatically. Needs sign-in.
Automatic reveals use ESPN's public data. They are not suitable for production and are for development only. Every output of this command and of round auto-reveal says so.
gamestage fixtures
gamestage fixtures --league soccer/eng.1 --date 2026-11-08 --team ArsenalWithout --league it lists each sport's leagues we have confirmed ESPN can score, and the questions each sport can reveal. The list is not written into the CLI: Gamestage reads ESPN's own list of leagues once a day and checks each one's scores, so a league appears when ESPN carries it and disappears when it stops. With --league it lists that day's matches, each with the fixture id to pass to round auto-reveal:
English Premier League on 2026-11-08
- Crystal Palace v Liverpool Sun 8 Nov, 14:00 UTC, not started
espn:soccer/eng.1/401879243A match reads "not started" with its kick-off in UTC, "live" with the score and ESPN's clock, "finished" with the score, or "called off". --json keeps ESPN's own status name and the time as ESPN gave it.
| Flag | Value | Default | What it does |
|---|---|---|---|
--sport <sport> | ESPN sport, such as basketball | every sport | Lists only that sport's leagues. |
--league <sport/league> | such as soccer/eng.1 or basketball/nba; eng.1 alone works when one sport has that league | none: lists leagues | Lists that league's matches. |
--date <YYYY-MM-DD> | a day | today, UTC | The day's matches, with --league. |
--team <name> | part of a team's name | every match | Only matches with that team, with --league. |
--all | off | Also lists leagues ESPN carries that were not confirmed, and why. |
A league the daily check has not confirmed yet is checked when you ask for it, and listed if ESPN's scores carry what a reveal needs; one checked in the last ten minutes is not checked again. A league that still cannot be revealed is refused with the reason. Before the first daily check has run on a new deployment, the list of leagues says to try again within the hour, while a league named in full is still checked when you ask.
round auto-reveal <game> --fixture <id>
Sets a predict game's edition to reveal its answers from a real match: the match on the edition, and a rule on each question. Needs sign-in. The same fields a producer sets in Studio under Results and closing.
Automatic reveals use ESPN's public data. They are not suitable for production and are for development only.
gamestage round auto-reveal saturday-predictor-3f2a --fixture espn:soccer/eng.1/401879246
gamestage round auto-reveal nba-night-91c0 --fixture espn:basketball/nba/401909936 --rule winner=resultIt names each question by its wording and says what it will be revealed from, or why it was left. The answers are saved in Studio and fans are scored about one to two minutes after ESPN marks the match finished: we read a live match once a minute and wait for a second reading that agrees. A postponed, cancelled or abandoned match voids the questions. Check or correct an answer with round reveal.
| Flag | Value | Default | What it does |
|---|---|---|---|
--fixture <id> | espn:<sport>/<league>/<event> from fixtures, or sportmonks:<id> | required | The match. |
--edition <id> | edition id | the game's one edition with questions | Needed when the game has more than one. |
--rule <question=rule> | repeatable | the sport's default | A question's rule, by the id round reveal lists. |
The rules, as fixtures lists them for each sport:
| Rule | Question | Football | Other sports |
|---|---|---|---|
result | choice | home, draw, away, after 90 minutes | home, away, overtime included |
both_score | choice: yes, no | did both teams score in 90 minutes | not offered |
clean_sheet_home, clean_sheet_away | choice: yes, no | did that side concede nothing in 90 minutes | not offered |
score | scoreline | the score after 90 minutes | the final score |
total | number | goals in 90 minutes | points, runs or goals, overtime included |
With no --rule, a choice question takes result if its option count fits (three for football, two otherwise), a number question total and a scoreline score. A question that fits none is left alone, and the command says which and why, so it can be answered with round reveal.
graphic templates
Lists the screens a graphic can be cut for. No account needed, no network call.
gamestage graphic templates| Template | Type | Made for |
|---|---|---|
lowerthird | Leaderboard | A lower third over live video, for TV and streaming. Transparent, three rows, keyed |
panel | Leaderboard | A right-hand panel pulled out over the picture, for TV and CTV. Eight rows |
bigscreen | Leaderboard | A stadium screen or a Jumbotron. Ten rows at large type. The default |
vertical | Leaderboard | A portrait panel in a concourse, 9:16 |
promo | QR | A QR code that sends a crowd to the game. No live data |
A template sets the graphic's size, type scale and safe margins. It does not set its colours: that is your stylesheet, and graphic dev is how you write one.
graphic create <game>
Puts the game's leaderboard on a screen. The control plane composes the graphic in Monterosa Live Graphics and hands you back an address.
gamestage graphic create kickoff --template bigscreen --consentOn screen
Game Kick Off (kickoff)
Template bigscreen - A stadium screen or a Jumbotron
Made for A crowd looking up at a screen from a long way away
Address https://<space-domain>/r/embed.html?slug=5aItiwK&bigscreen=true| Option | What it does |
|---|---|
--template <id> | Which screen to cut it for. Default bigscreen. See graphic templates |
--consent | Confirms the people named agreed to appear on a screen. No default |
Open the address on the screen. It is a web page, it needs no sign-in, and it follows the game's leaderboard by itself: fans play, the graphic redraws, and nothing is redeployed for a new round.
--consent has no default and --json does not imply it. A leaderboard puts fans' names on a screen other people can see, and somebody has to say those people agreed to that. Your account is stored on the graphic as the one who confirmed it. A flag that defaulted to true would make that record say somebody agreed when nobody was asked, which is worse than having no gate.
| Refusal | What to do |
|---|---|
Nobody has said these names can be shown | Run it again with --consent, once that is true |
No template called <id> | Run gamestage graphic templates |
This game has not been deployed | A graphic follows the game's own leaderboard, and a QR code sends people to the game's page. Neither exists before a deploy. Run gamestage deploy <game> --dir . |
This deployment cannot make graphics | The control plane holds no Live Graphics key. That is a deployment setting, not anything about your game |
Your machine never holds a graphics credential. Live Graphics takes one key per deployment, and that key can write to every graphic in it. The control plane holds it, checks the game is yours, and makes the call. Nothing is written to your game's files and nothing about your game changes.
graphic list <game>
The graphics this game has, their ids, and where to watch them.
gamestage graphic list kickoffEach row carries the template, the graphic's id, its address, and who confirmed the names could be shown. The id is what graphic remove takes.
graphic remove <game> <id>
Takes a graphic off the air. The address stops answering, so take the screen down first if somebody is watching it.
gamestage graphic remove kickoff 42a57df0-6caf-46a8-ad5f-a7aeb8a7030fA graphic this game does not hold is refused, whoever asks. That refusal is the only thing between one creator and another customer's screen, because the key that deletes a graphic has no tenancy of its own.
graphic dev
Serves the Live Graphics renderer on your own machine, drawing a made-up leaderboard with your stylesheet applied, so you can restyle a graphic without looking at a production screen to find out whether a colour was right. Needs no account.
gamestage graphic dev --template lowerthird --background ~/plates/grass.jpg| Option | Type | Default | What it does |
|---|---|---|---|
--css <path> | path | graphic.css | The stylesheet to preview. A missing file draws the template on its own. |
--template <id> | template id | bigscreen | Which template to draw, from gamestage graphic templates. An id that does not exist is refused and the real ones are listed. |
--background <path or url> | path or URL | none | An image (.jpg, .png, .webp, .avif, .gif, .svg) or a video (.mp4, .webm, .mov, .m4v) to draw the graphic over. A missing file, or one that is neither, is refused before anything is served. |
--rows <rows> | number | 10 | How many players the sample board holds. The template decides how many show at once, as it does on air. |
--bigscreen | flag | off | Draw it as a big screen rather than an overlay. |
--accent <colour> | #rrggbb | the template's | The accent colour. |
--port <port> | number | 4321 | The port to serve on. |
--renderer <url> | URL | the dev Space's renderer | Where the Live Graphics renderer is served from. |
Judge a keyed template over a picture. lowerthird and panel go to air over live video, so check them over the worst picture they will meet: grass in sunlight, a white kit, a bright crowd. Pass --background and the page draws that picture behind the graphic, showing through wherever the template leaves the page clear, which is what a vision mixer does with it. A video loops, muted. bigscreen and vertical paint their own ground and cover the picture, because they own the whole screen.
Use a clip encoded as WebM if you preview in Chromium: Chromium cannot play H.264, so an .mp4 that plays in Chrome shows black there.
The page is the real renderer, not a copy of it. The markup and the script come from the deployed graphic, so what you see is the thing itself rather than something that resembles it and quietly stops matching.
Save the stylesheet and the page picks it up within five seconds. There is no watcher and no reload: a graphic re-reads its stylesheet on every poll, so this gets live editing by not getting in the way of behaviour the renderer already has.
It reads no graphic and writes none. The rows are invented, so there is no production board to get wrong.
The structure is not yours to change, only the paint. A graphic's type is built by Monterosa and its markup is fixed, which is what stops a stadium screen rendering something nobody designed. Your stylesheet is applied over it.
graphic push <game>
Hands a producer the address of your stylesheet, so the graphic they composed can follow it. Needs an approved account.
| Option | Meaning |
|---|---|
--css <path> | The stylesheet to publish, default graphic.css |
gamestage graphic push kickoff --css graphic.cssReady for a producer
Game Kick Off (kickoff)
Stylesheet graphic.css (3,204 of 10,000 characters)
Address https://<space-domain>/games/kickoff/graphic.cssNothing is written to Live Graphics, by design. Writing to a graphic needs a key belonging to a whole deployment, or a Studio operator's own token, and a creator has neither. Giving a creator one would make Gamestage the only thing standing between them and another customer's stadium screen.
So the stylesheet travels the way the leaderboard already does. deploy publishes it along with every other file in the directory, a producer pastes its address into the graphic beside the feed address, and the graphic follows it from then on. You restyle a live screen by deploying. The producer takes it back by clearing one field.
What this command does is make that usable: it reads the stylesheet, refuses it if it will not fit, checks the address is actually being served, and prints the line to hand over.
| It stops with | When |
|---|---|
No stylesheet to publish | The path does not exist |
The stylesheet is too long for a graphic | Over 10,000 characters, which is the field Live Graphics stores it in. Minify it |
This game has not been deployed | Nothing is served yet, so there is no address to give |
The stylesheet is not being served yet | Nothing answers at the address, usually because the file was written after the last deploy or sits outside the deployed directory. The playground says 403 rather than 404 for a file that is not there, so the command reports whatever it got rather than guessing |
Deploy first. The address only starts working once a deploy has published the file, and a deploy publishes the directory it is given, so the stylesheet has to be inside it.
Live Graphics does not read a stylesheet address. A producer opens the address this command prints and copies the stylesheet out of it by hand, rather than the graphic following it directly. See Live Graphics for how a graphic gets its style today.
domain add <game> <hostname>
Serves the game from an address of your own, such as quiz.myclub.com, and prints the DNS record to create. Publisher includes one custom domain and Enterprise more by contract; Starter is refused with the reason.
gamestage domain add the-limit quiz.myclub.com--move takes your plan's domain off its other game and puts it here. The whole route, statuses included, is in Use your own domain.
domain status <game>
Checks the record and the certificate now, and says where the domain is: waiting for DNS, issuing a certificate, live, not pointing, or failed with the reason. --watch checks every 15 seconds until it is live or failed.
gamestage domain status the-limit --watchdomain remove <game>
Stops serving the game from its custom domain. The game's own address keeps working.
gamestage domain remove the-limittheme init <name>
Starts a theme of your own for Gamestage UI: theme.json (its name, version and fonts), tokens.json (every role the library has, with today's value) and an empty overrides.css, in <name>-theme unless you pass --dir.
gamestage theme init harbourtheme figma pull <file.fig | figma-url>
gamestage theme figma pull "Brand kit.fig" --out figma-export
ls figma-export figma-export/assetsReads a Figma design and writes what it finds to --out (default ./figma-export): export.json, and the file's logos, marks and pictures in assets/. Nothing is sent to Gamestage.
Start from a downloaded file. Ask the customer or operator for the design as a .fig: in Figma, open the file, then File, Save local copy. A .fig needs no token and no network, and it holds every variable collection, mode and value (which Figma's API gives only on an Enterprise plan) and every bitmap the design uses. If Save local copy is missing from the menu, the organisation or project has switched off downloads for that file, and the file's owner has to download it and send it.
Add a link only for pictures Figma has to draw. A .fig holds no picture of a screen and no rendered vector logo, and the CLI does not draw them. When you need frame PNGs to compare against, or a logo that is drawn in vectors, pull again with a link to the frame (Share, Copy link to selection) into another folder. A link pull uses your own Figma token, read only from the environment variable FIGMA_API_TOKEN (a personal access token that can read files); it is never an argument, is not printed or saved, and goes only to api.figma.com. The only other addresses fetched are the image addresses Figma returns.
The argument is read as a file when it is a path ending .fig, or an existing file that opens like one, and as a link otherwise.
A file is walked over up to 200 frames and 50,000 layers, and names up to 300 logos and team marks and 100 backgrounds, where a link pull takes 50 frames, 5,000 layers, 30 logos and team marks and 10 backgrounds. Pages whose name contains "archive", in any case, are skipped, and source.skippedPages names them. A bitmap that only a skipped page uses, or only a component no kept page uses, is not exported, and a warning says how many were left out.
A frame inside a group or a section is found like one placed on the page, and a link to a group gives the frames inside it. Layers outside any frame, such as a colour swatch on the page, are still read for values and assets, and a warning names them, because they have no entry under frames and no PNG. A link to a layer that holds no frame gives its values and a warning saying so.
What a downloaded file gives
Part of export.json | From a .fig | From a link |
|---|---|---|
source | kind: "file", the file name, Figma's name for it and export time from the file, formatVersion, layers (every layer in the file) and the pages | The file key, name, last-modified time and the source nodes |
frames | Each frame's id, name, type, width and height; png is null with pngError saying why | The same, with a PNG of each frame at scale 1 |
renders | { "available": false, "reason": ... } | Not present |
values | The same summary, from the same bounded walk over the same frames | |
styles | Every style in the file (FILL, TEXT, EFFECT, GRID) with key, name, type, description, nodeId, remote (copied from a library) and, for fill and text styles, value | Figma's published styles |
variables | Every collection (id, key, name, modes, defaultModeId, remote, paintUses) and variable (id, key, name, collection, type, remote, paintUses, valuesByMode, resolvedValuesByMode) | Local variables, or unavailable with the reason when Figma refuses them for your plan |
assets | Bitmaps copied out of the file, plus vectors: logos and marks that need a link to render | Logos and marks as SVG, backgrounds as PNG, rendered by Figma |
valuesByMode is in the shape Figma's API uses: a colour as { r, g, b, a }, an alias as { "type": "VARIABLE_ALIAS", "id": ... }. resolvedValuesByMode is what each value comes to, per mode: mode (its name), value (a colour as hex, #rrggbb or #rrggbbaa, a number, a string or a boolean), via (the variables an alias passed through) and, when it could not be worked out, value: null with unresolved giving the reason. An alias into another collection takes the mode with the same name there, or that collection's first mode. A colour at an opacity ("Blue 600 at 30%") is worked out too.
A file keeps a copy of every library version it has used, so one collection name can appear several times. paintUses counts the fills and strokes that point at a variable, or at any variable in a collection: the copy with uses is the one the design is built on.
Bitmaps come from the file's images/ folder, one file per picture whatever the number of layers that show it, up to 300 pictures, 32 MB each and 1 GB in all. Each is named by the same rules as a link pull (the table below), and any other picture is image-<layer name>. The file type comes from the bytes, so a photo is .jpg and a crest is .png. Each item has file, kind (logo, team-mark, background or image), format, nodeId, name, label (team marks), width and height in the design, bytes, imageRef (the picture's SHA-1 in the file) and, for a PNG, pixels.
A downloaded file is refused with its own error.code, exit 2:
| Code | What happened | Next |
|---|---|---|
not_a_fig | No file at that path, or it is not a Figma design file | Save local copy from Figma again and give that file |
unsupported_version | The file's format version is outside what this CLI reads | Update the CLI, or pull with a link |
corrupt_chunk | The file is damaged | Save a fresh local copy |
too_large | A part of the file, or its layer count, is over the limit this command reads | Save a copy with only the pages you need |
What a link gives
export.json has schemaVersion: 1, the file key, name and last-modified time, and the source nodes. Per frame it has the PNG's path and size, and flattened: true when the frame is one image with no text or vectors to read. It has a values summary: every distinct text style (family, weight, size, line height, letter spacing, case, alignment) with a count; solid fills and strokes as hex with counts; corner radii; auto-layout padding and spacing; Figma's published styles; and local variables, recorded as unavailable with the reason when Figma refuses them for your plan. It maps no roles and invents no expected values: your agent decides what each one is for. The walk is bounded by node, depth and frame limits, and export.json says when one was reached.
Assets
assets/ is written by default. Pass --no-assets to skip it. This section describes a link pull; a downloaded file names its bitmaps by the same rules and copies them rather than rendering them. Use these files in the game, and draw a stand-in only for what the Figma file does not have.
| Kind | Which nodes | File |
|---|---|---|
logo | A node named with the word logo or mark ("Club Logo", "TeamMark"; "Bookmark" does not count), up to 800px on a side | SVG, assets/logo-<name>.svg |
team-mark | In a button or row where one child holds the text label (at any depth, so "Pittsburgh" and "Pirates" on two lines in a frame count as one label), the first other child that is an icon or crest (16 to 200px, a vector, an image, or a group of them with no text). Named from the label. Rows with several labelled children are lists and give nothing | SVG, assets/team-<label>.svg |
background | A node with an image fill, or named background, bg, texture or pattern, that is wider than 300px or covers most of its screen. A small layer named "..._BG" is never one, and neither is a layer named for a club, team, crest, badge, logo, mark or icon | PNG, assets/background-<name>.png, at scale 2, lowered so the long edge is at most 2400px |
A node picked once is not searched further, so the parts of a logo are not exported again. A component or row label that appears on several screens is exported once, and assets.duplicatesSkipped counts the repeats. At most 30 logos and team marks and 10 background images are exported, and assets.limits says when a cap was reached.
export.json has an assets section: enabled, items, duplicatesSkipped and limits. Each item has file (relative to --out), kind, format, nodeId, name, label (team marks), width and height in the design, bytes, and for a PNG pixels (the size of the file). With --no-assets, the section is { "enabled": false }, and --json prints "assets": "skipped".
Something not exported is named in warnings with the reason: a background with text on it (an export would bake the text into the picture), a background that is one flat colour (its value is already listed), a logo-named node over 800px, or a render Figma would not give. These do not stop the pull. A rejected token (token_rejected) or a rate limit (rate_limited) while rendering ends it, as anywhere else.
A link pull's refusal exits 2. With --json, error.code is token_missing, token_rejected (Figma 401), access_denied (403), not_found (404), rate_limited (429, with retryAfterSeconds when Figma gives one), network, or invalid_url for a link that is not Figma's.
export FIGMA_API_TOKEN=...
gamestage theme figma pull "https://www.figma.com/design/<key>/<name>?node-id=1-2" --out figma-export
ls figma-export/assetstheme draft <figma-url | file.fig | export.json>
Reads Figma on your machine, as theme figma pull does, and has Gamestage draft a theme from the values: each role with the Figma value it came from and why, held to the library's theme check. Only the values are sent; never the token, the file or a picture. Organisation admins only. Prints the draft's id and a Stage link that draws it on real components. --name, --org, --json. Draft a theme from Figma is the whole guide.
gamestage theme draft "Kestrel Cup.fig" --name kestreltheme revise <draft> ["<instruction>"]
A new revision of a draft from plain words, changing only the roles the words are about. --to <n> goes back to revision n instead, as a new revision.
gamestage theme revise td-4k2m9q7x1c3b "make the buttons less round"
gamestage theme revise td-4k2m9q7x1c3b --to 1theme drafts
Your organisation's drafts, newest first.
theme from-draft <draft> [dir]
Writes a draft's theme.json and tokens.json to a folder that theme check and theme publish take, never into one that already has a theme.json. --revision <n> writes an earlier revision.
gamestage theme from-draft td-4k2m9q7x1c3b kestrel-theme
gamestage theme publish kestrel-themetheme check [dir]
Runs the library's checks over the theme: contrast, the type scale, keys the library does not have, and each override, which is a warning. A font the game carries must be in the theme's folder at its path, and be a font file. Exits non-zero when an error would stop it being published.
gamestage theme check harbour-themetheme preview [dir]
Shows the main components wearing the theme in a local page, rebuilt as you edit. --port picks the port.
gamestage theme preview harbour-themetheme publish [dir]
Checks, builds and stores the theme as name@version, privately for your organisation. A theme that fails an accessibility check is refused. A font's src is the https address of the file on your own host, or its path inside the game, such as fonts/harbour-sans.woff2, with the file at that path in the theme's folder: publish sends the file with the version. Never a font service or a Gamestage address. Each font needs a declaration that you may use it in web games: publish asks for it at a terminal, and --declare-fonts makes it in your name when there is none. See ship your own font with your theme. A published version never changes; raise the version to publish again. When your workspace belongs to an organisation, only an organisation admin can publish: see who can change it.
--org <id> publishes as that organisation for this command only, when you are its admin, without the org use choice that stays until you change it. Anything else is refused with error.code not_org_admin.
Without a terminal, or with --json, theme publish never asks a question. If a font has no declaration it exits non-zero, and --json gives { "ok": false, "error": { "code": "fonts_not_declared", "fonts": ["Harbour Sans"] } } with the statement for each font alongside. Show each statement to the person who is publishing, and run it again with --declare-fonts only when they say yes.
After publishing it prints the version's page on Stage, with the preview, fonts, check and the games that use it, as See it on Stage:. With --json the address is url.
gamestage theme publish harbour-themetheme approve <name@version> --note <text>
Records that the customer signed off that version (GS-1906). The registry then serves it as theme-<name>@approved, which is what Fantenna follows. --note is required and says where the sign-off came from. Organisation admin only, as publishing is. --org <id> approves another organisation's theme, for this command only, when you are its admin. With --json, the answer is the approval: name, version, approvedBy, approvedAt and note.
gamestage theme approve harbour@1.1.0 --note "Harbour brand team, email of 3 Dec"theme list
Your organisation's themes and every version, with who published each, which version is approved and on whose word, and each theme's page on Stage. --org <id> lists another organisation's, for this command only, when you are its admin. With --json, each theme carries its page's address as url.
A theme's page is https://gamestage.ai/stage/design-systems?theme=<name>, with &version=<version> to open one version. Stage shows the themes of the workspace you are in; when the command ran in a shared workspace, the address also names it, and the page offers to switch if you open it from another.
gamestage theme listtheme use <name> or <name@version>
Run in a game's folder. Installs the theme from your organisation's private registry as app/gamestage-theme-<name>.css, with any font the game carries at its path (such as fonts/harbour-sans.woff2), and pins the exact version in gamestage.yaml as experience.design.system: a bare name means the newest. Then it wires the theme in and says what it changed: data-gs-theme="<name>" on <html> in index.html, and the stylesheet imported in the module script index.html names, or linked in a plain page's <head>. gamestage verify checks the theme is installed and set, and deploy refuses a game whose theme font is missing. Run it again to move the game to a new version; a second run adds nothing twice. Any member can run it, including an account waiting for approval. --manifest names the manifest when it is not gamestage.yaml. With --json, changed lists each edit and fonts the font files it added. --org <id> is accepted only when it is the organisation the game's workspace belongs to; any other is refused as not_org_admin, because a game may use only its own organisation's themes. The install reads the same workspace and organisation as the rest of the command: the shared workspace you chose with gamestage workspace use or GAMESTAGE_WORKSPACE, and the organisation --org names. A workspace you are not a member of is refused as not_a_member and nothing is installed.
gamestage theme use harbour
gamestage theme use harbour@1.0.0org context
Prints your organisation's integration context: one Markdown file, set by an organisation admin, that says how a game fits your app. With none, it says so in one line. --save writes it to integration.md here, or --save <path> to a path of your choice, for your agent to read. Any member can run it, including an account waiting for approval. See Your organisation's integration context.
gamestage org context --saveorg context set <file>
Publishes the file as a new revision for everyone in your organisation. Organisation admins only: see who can change it. Refused before anything is sent when the file is empty, over 50 KB, not UTF-8 text, or has a line that looks like a secret; the line is named and the value is not repeated.
gamestage org context set integration.mdorg context history
Every revision, newest first, with who set it, when, and its size.
gamestage org context historyorg starter publish <folder>
Zips the folder and publishes it as a new version of your organisation's starter app, named by the gamestage-starter.json inside it. Gamestage checks the upload before anybody can use it, and a refusal names every check that failed. Organisation admins only. See starter apps.
gamestage org starter publish ./web-embed --check
gamestage org starter publish ./web-embedA publish runs the checks on your machine first and stops before the upload when any fails.
| Option | What it does |
|---|---|
--check | Runs the checks on your machine and stops: no sign-in, nothing uploaded or published. Exits 1 when a check fails. With --json: { ok, problems, files, bytes, left_out }. |
org starter list
Every starter app your organisation has, with its newest version in use, its framework, the formats it plays, and who published it. Retired versions are left out unless you add --all. Any member can run it, including an account waiting for approval.
gamestage org starter list
gamestage org starter list --allorg starter retire <name@version>
Stops create choosing that version, and leaves it out of org starter list. Nothing is deleted: a game made from it keeps working, and it can still be named exactly with create --starter name@version. When every version of a starter app is retired, create starts from the format's own page. Organisation admins only. See retire a version.
gamestage org starter retire web-embed@1.1.0org admins
Lists your organisation's admins, who change its integration context, starter apps and themes, and says whether you are one. Any approved member can run it.
gamestage org adminsorg use <organisation>
For Monterosa people who are admin of customer organisations: chooses which customer you are working as. Your next org context set, org starter publish and theme publish change that customer's files. Your own games keep Monterosa's settings whichever you choose. --home goes back to your own organisation's files. Admin of one customer and not of Monterosa, you are working as that customer without choosing. Admin of more than one, Monterosa included, a publish is refused until you choose, and the refusal names this command. Anyone else gets a refusal that says their organisation decides it.
gamestage org use nba
gamestage org use --homecdn put <file>
Publishes one file to cdn.gamestage.ai, for Studio or a game's clients to fetch by URL, at https://cdn.gamestage.ai/apps/<org>/<app>/<version>/<name>. Organisation admins only. JSON, HTML, PNG, JPEG, SVG or WebP, up to 2 MB. A file at an address never changes: a second put to the same app, version and name is refused with file_exists, so publish a change under a new --app-version. --name publishes it under another name, and --org works as another organisation you are admin of, for this command only. Host files on cdn.gamestage.ai has every rule.
gamestage cdn put spec.json --app predictor --app-version 1.0.0cdn ls
Lists your organisation's files on cdn.gamestage.ai and their addresses. --app lists one app's files.
workspace members
Lists the people in the workspace you are acting in: its owner, members, and invites not yet accepted, with how many of the five places besides the owner are used. Anyone in the workspace can run it.
workspace invite <email>
Invites a colleague to your workspace. Owner only. They join by signing in to Gamestage with that address, verified, and then running gamestage workspace use. A workspace holds its owner and at most five others, counting invites not yet accepted. While Gamestage is in preview, invite people at their work address: Gmail, Yahoo and other personal addresses cannot join.
gamestage workspace invite amit@monterosa.co.ukworkspace remove <email>
Removes a member, or cancels an invite. Owner only. It takes effect on their next request.
workspace use [id]
Acts in a workspace you are a member of: every command after it acts there. Leave out the id to list the workspaces you can act in, and use --own to go back to your own. GAMESTAGE_WORKSPACE=<id> does the same for one command or a CI job. The control plane checks your membership on every request, so a member who is removed is refused on their next command, whatever this says.
A member can build, register and deploy games in the workspace. The account stays the owner's: only they invite or remove people, or change the plan, profile, terms or GitHub link. Each change is recorded against the person who made it.
workspace signal [on|off|status]
gamestage workspace signal onSwitches Monterosa Analytics (Signal) on or off for every game in the workspace, the same switch as Stage's Analytics page. Leave out the state, or say status, to see whether it is on. It needs a Publisher or Enterprise plan and is off until somebody switches it on. Your games collect only from fans who consent, and it needs no change to your code. Switching it off stops collection and keeps the events already collected.
Monterosa can also switch Monterosa Analytics off for the whole service. While it is off, your workspace's switch is kept but nothing is collected, and an analytics address typed into a game's settings in Studio is ignored too.
On Starter, on is refused with the plan it needs and exits 1. With --json the refusal is ok: false with code: "tier_required".
ads request <game>
Asks Monterosa and the retail partner to approve partner products on the game's result screen. Products are in preview, and using them is subject to approval and to commercial terms agreed with Monterosa. Every fact is a flag, and the command names any you leave out.
gamestage ads request the-limit --audience "Club fans in the UK, mostly adults" \
--where "the club app and website" --countries "United Kingdom" --no-prize| Flag | Required | What it is |
|---|---|---|
--audience <text> | Yes | Who the game is for. |
--where <text> | Yes | Where it is played. |
--countries <text> | Yes | The countries its fans are in. |
--prize, --no-prize | Yes, one of them | Whether the game has a prize. A prize promotion's terms can forbid ads. |
--note <text> | No | Anything else Monterosa should know. |
You can change your answers by running it again until Monterosa picks the request up. After a decline you can ask again. Ads has the whole route.
ads status <game>
Says where the game's request is and what happens next: requested, with Monterosa, with the retail partner, approved (products are on) or declined, with the reason. --json carries asked, which is true once the game has a request or a recorded no.
gamestage ads status the-limitads skip <game>
Records that you do not want products in this game, so an agent does not ask again. ads request still works if you change your mind.
gamestage ads skip the-limitendpoint <game> [which]
Prints where a deployed game answers. which is player, control or playground; all three when omitted. Needs sign-in.
logs <game>
Tails a game's runtime log. Needs sign-in.
| Option | Meaning |
|---|---|
--limit <n> | How many lines, newest kept, default 100 |
--since <iso> | Only lines after this timestamp |
--level <level> | info, warn or error |
usage <game>
What a game's Jev questions have cost: per round, in total, and per fan's game, which is one fan playing one round. Mystery games only, since they are the ones that ask Jev. Needs sign-in.
npx gamestage usage who-am-iwho-am-i: Jev usage
Questions answered 4515
Fans' games 1147
Total $0.57
Per fan's game $0.0005
Priced at $0.042 per million input tokens, output free
2026-07-30 781 questions 197 fans $0.10
2026-07-29 2104 questions 538 fans $0.27
2026-07-28 1630 questions 412 fans $0.21Questions the fallback answered when Jev could not are counted separately and cost you nothing. With no TypeSafe key connected it says so, because the game cannot answer questions until one is. --json gives the same numbers as data.
results <game>
Shows how fans played a round: how many made a play, what they picked for each question, and how many called each one right once there is a result. Works before a round opens, while it is open and after it settles. Needs an approved account, and only reads games in your own workspace.
npx gamestage results traitors-finale-3f2atraitors-finale-3f2a: results
Round "Who wins?" (finale): open, locks 30 Oct 2026 20:00 UTC, 412 played, the round fans are served now
Entrants 412
Finished 412
Called every one not settled yet
- Entrants are fans who made a play. Fans who opened the game without playing are not counted here: the Engine only sees plays.
Who wins?
- 412 answered, no result yet
Faithful 254 62%
Traitor 141 34%
Nobody 17 4%| Option | Type | Default | What it does |
|---|---|---|---|
--round <id> | round id | the round fans are served now | Reads another round. The output lists the game's other rounds with their ids and the date each locked or opens. |
--watch | flag | off | Reads again every 15 seconds and prints only when a figure changed. Stop it with Ctrl+C. |
--json before the command prints the figures as data; with --watch, one line of JSON per change. Our own test plays are left out of every figure. Fans who opened the game and left without playing are not counted, because the Engine only sees plays; the output says so rather than showing a visitor number. If a round has more fans than one read can cover, the output says the figures are a minimum.
Predictions show picks per question, and "Called every one" counts fans who called every question exactly, leaving out any question that was voided. Other formats show entrants, finished and won, with no per-question breakdown. Mystery, Arcade and Quiz games run on other Engines and are refused with a message saying so.
leaderboard <game>
Shows a round's leaderboard by fan name, or the running total across a whole edition. Needs an approved account.
npx gamestage leaderboard traitors-finale-3f2a --edition --limit 10| Option | Type | Default | What it does |
|---|---|---|---|
--edition [id] | edition id, optional | off | Shows the edition's running total instead of the round's board. With no id, the edition of the round fans are served now. |
--round <id> | round id | the round fans are served now | Shows another round's board. gamestage results <game> lists the ids. |
--limit <n> | 1 to 200 | 50 | Rows shown. The total ranked is always printed. |
--watch | flag | off | Reads again every 15 seconds and prints only when the board changed. |
--json and --watch work as they do for results. A round with no Studio edition has no edition board, and the command says so. Boards show fans' names and never their account ids.
plan <plan>
Changes this workspace's plan, and so its limits. Takes runtime, live or enterprise, which a creator reads as Starter, Publisher and Enterprise. Needs sign-in.
Only runtime can be set here. Publisher and Enterprise are arranged with a person and no payment is captured on this command, so asking for either is refused with operator_required and your workspace is left as it was.
This changes a record. It is not evidence that commercial approval, a Monterosa org or dedicated infrastructure exists, and none of those can be created by the service account. See Plans and limits.
promote <game>
Approves your own game to move from dev to prod. Needs your account approved.
Succeeds for a game that exists, is not archived and is not already approved: approving your own game is not a purchase, so there is nothing for a plan to refuse here. Run it again on an approved game and it reports there is nothing to do. It does not put the game live on its own. Reaching fans on prod also needs your workspace on a paid plan, which only Monterosa can do, and the command tells you which of the two states you are actually in afterwards.
Stage carries the same action, under "Dev and prod" on a game's own page. It shows both gates, which of them is open, and which of the two states the game is serving right now.
suspend <game>, wake <game>, archive <game>
Take a game off the air and free its live slot; put a suspended game back on the air; take a game off the air for good while keeping its record, id and files. All three change what fans can reach, so they belong to a person rather than an agent. There is no creator-facing delete. Needs sign-in.
prune
Deletes archived games that never deployed. Needs sign-in.
| Option | Meaning |
|---|---|
--yes | Do not ask before deleting, default off |
It lists what it found, grouped by name, and then asks. Without a terminal and without --yes it deletes nothing. A game that is live, or that ever deployed, is refused by the server rather than by the command, so a mistaken --yes cannot take a real game away.
admin onboard <workspace>
Ours, not yours: it is refused for anybody who is not a Monterosa operator. It gives a customer's workspace a paid plan and a Studio organisation and space of its own, and invites their people to Studio. Run it with no options and it asks for what it needs:
$ gamestage admin onboard ws_039c4b91137bd8b9bb6b
Workspace
Workspace Plucky (ws_039c4b91137bd8b9bb6b)
Owner mackenzie@plucky.com
Plan Starter
Organisation None
Games in Studio Plucky FPL Points
This Studio dev
Which organisation is this customer?
1. Formula 1 (formula1)
2. NBA (nba)
Or type the name of a new one, such as Plucky.
> PluckyIt then asks which Studio the customer is on, whether they already have a Studio organisation there, which space their games go in, which email domains join, which plan, and who to invite. It prints every step as a numbered list and asks once before changing anything:
What this will do
1. Create the space "Gamestage" in the Studio organisation Plucky.
2. Record the organisation Plucky (plucky) in Gamestage, pointing at that Studio organisation and space, with the domains plucky.com.
3. [already so] Workspace ws_039c... joins plucky through its owner's address, mackenzie@plucky.com.
4. Move workspace ws_039c... from Starter to Publisher.
5. Invite mackenzie@plucky.com to Studio as creator of the space Gamestage.
- One game stays where it is in Studio: Plucky FPL Points. A game's Studio project never moves. Only games created after this land in the new space.
Go ahead? Type yes to do it:Every question is also an option, so the same thing runs unattended:
gamestage admin onboard ws_039c4b91137bd8b9bb6b --org plucky --name Plucky \
--studio-org 607354e1-2948-4335-92d8-1043cc61c7bd --new-space Gamestage \
--domain plucky.com --invite mackenzie@plucky.com --yes| Option | Value | Default | What it does |
|---|---|---|---|
--org <id> | lower case letters, digits, hyphens | asked | The customer's organisation in Gamestage. Made if it is new, which needs --name. |
--name <name> | text | asked for a new organisation | The organisation's name. |
--domain <domain> | an email domain, repeatable | the owner's domain, when asked | Workspaces whose owner is at this domain join the organisation. |
--studio-host <host> | dev, us or eu | the Studio this control plane is connected to | Which Studio the customer's organisation is on. |
--studio-org <id> | a Studio organisation id | asked | The customer's existing Studio organisation. |
--new-studio-org <name> | text | none | Make a Studio organisation with this name. |
--space <id> | a Studio space id | asked | An existing space in that organisation for their games. |
--new-space <name> | text | Gamestage, when asked | Make a space with this name. |
--plan <plan> | starter, publisher, enterprise | publisher | The plan the workspace moves to. |
--attio-company <id> | an Attio record id, or the company's address copied from Attio | asked; Enter leaves it unlinked | The customer's company in Attio, so the CRM can show their plan. |
--invite <email> | an address, repeatable | the owner, when asked | Someone to invite to the space in Studio. |
--role <role> | viewer, creator, admin | creator | Their Studio role, on that space only. |
--yes | flag | off | Do it without asking. |
Without --yes and without a terminal it prints the plan and changes nothing.
A step that is already so is marked and skipped. Running the command twice changes nothing the second time, and a run that stopped half way can be run again with the same answers.
Somebody you name who is already in the customer's Studio organisation is not invited again. If they cannot see the space they are given the role on it, keeping every role they hold, and if they already can nothing changes. The closing summary says who was emailed and who already had a sign-in.
What it does not do:
- Move an existing game. A game's Studio project stays in the space it was created in. Only games created afterwards land in the new space. The plan lists the games that stay.
- Reach another Studio. A control plane is connected to one Studio. Naming a different one is refused, because the organisation's Studio is recorded and not yet used to choose where its games are created. Run the command against the control plane connected to that Studio, with
GAMESTAGE_CONTROL_URL.
When it refuses, it lists every reason at once and changes nothing:
| It says | What to do |
|---|---|
Studio dev has no organisation ... that our key can see | Check the id. If it is right, ask a Studio admin to add the Gamestage service account to that organisation. |
Our key's role on the Studio organisation ... is viewer | Ask a Studio admin to make the Gamestage service account an admin of it. |
The Studio organisation ... already belongs to ... | Two customers never share one. Name the customer's own, or make one. |
The domain ... already belongs to ... | Leave the domain out and the workspace joins by a grant instead. |
Workspace ... already belongs to the organisation ... | Name that organisation, or take the workspace out first with gamestage admin ungrant. |
This control plane creates games on Studio dev, and you named Studio us | Run it against the control plane connected to that Studio. |
This control plane cannot onboard a customer yet | It needs a Space deploy, or it is not connected to a Studio. |
If Studio will not take an invitation through its API, the run still finishes everything else, then prints the invitation as three steps to do in Studio by hand: open the organisation, Members, Invite, with the role on the space.
If any other step fails part-way, it stops, says which step and what Studio answered, and lists what was done before it. Fix the cause and run the same command again.
When it finishes it prints what to tell the customer and three checks: open the space in Studio, read the workspace's organisation with gamestage admin grants, and deploy a new game and see its project in the space.
admin approve <workspace>, admin refuse <workspace>, admin remind <workspace>, admin plan <workspace> <plan>, admin grant <workspace> <grant>, admin ungrant <workspace> <grant>, admin grants <workspace>, admin workspace create, admin workspace rename <workspace> <name>, admin workspace convert <workspace>, admin workspace owner <workspace> <email>, admin org list, admin org show <org>, admin org set <org>, admin trial <workspace> <limit> on|off, admin trials <workspace>, admin features, admin features set <plan> <service> on|off, admin features <workspace> [<service> on|off|plan], admin refresh <workspace> <dataset> <hours>, admin source-on <workspace> <source>, admin creator-sync, admin domains, admin erase <game>, admin close <workspace>, admin erasures
Ours, not yours. Approving an account and moving it onto a paid plan are decisions we take, so these are refused for anybody who is not on the operator allowlist, and the refusal says so rather than pretending the command does not exist. They are listed here because they are in gamestage --help and an unexplained command is worse than a documented one you cannot run.
admin remind emails a waiting applicant a link to finish their application at https://gamestage.ai/stage, naming what is still missing. It sends at most one a day and is refused once the account is decided or nothing is missing. An operator can approve an account before it is finished; you still accept the Terms of Service yourself before you can deploy.
admin plan is how a person moves you when plan tells you a plan is arranged with a person. It changes your limits and nothing already running: a live round keeps the caps it was given until you deploy the game again. --live-games <count> sets the live-game ceiling instead of the plan's own, and 0 means none.
admin grant, admin ungrant and admin grants are how we make someone an admin of your organisation, as Your organisation's context, starter apps and themes describes. A grant is one of two kinds:
| Grant | What it does |
|---|---|
org:<organisation> | Puts the workspace in that organisation, as an email address at its domain does. |
org-admin:<organisation> | Lets the workspace change that organisation's integration context, starter apps and themes. The workspace must already belong to the organisation, with one exception: a Monterosa workspace can also be admin of customer organisations, and works as one of them at a time with gamestage org use. Its own games keep Monterosa's settings. |
$ gamestage admin grant ws_01J9 org-admin:monterosa
Grant added
Workspace ws_01J9
Grant org-admin:monterosa
Grants now org-admin:monterosa
Decided by operator@monterosa.co.ukAdding a grant the workspace already holds, or removing one it does not, prints "Nothing to do" and exits 0. Anything else that cannot be done is refused with the reason and exits 1: a grant of another kind, an organisation that does not exist, an admin grant for an organisation the workspace does not belong to, a second organisation, or removing the org: grant an admin grant depends on. Each change is recorded in the workspace's audit trail with who made it. With --json, admin grant and admin ungrant print status (added, removed, unchanged or refused), changed, grant, grants, previous and, on a refusal, code. admin grants prints the grants, the organisation the workspace belongs to and whether it is an admin, or, for a Monterosa workspace that is admin of a customer, which customer (admin_for in --json).
admin workspace create, admin workspace rename and admin workspace convert set up the workspaces on a customer's Space. A customer's Space runs with PERSONAL_WORKSPACES=off, so signing in there creates an account record rather than a personal workspace: a person's one personal workspace is on the main Space, and the customer's people work in a team workspace. create --name <name> --owner <email> [--org <id>] makes that workspace, approved and named, in the organisation when one is given, and invites its owner, who takes it up on their next sign-in and invites their colleagues from there. Anybody who signs in lands in the team workspace they belong to without choosing it. rename changes a workspace's name. owner names a workspace's owner by address: on a team workspace it invites them as owner, and on one somebody's sign-in created it fills in the address that sign-in could not verify. convert turns an empty personal workspace made before the change into an account record, keeping its approval, terms and audit, and refuses one that holds games, members or open invites. Point the CLI at the customer's control plane with GAMESTAGE_CONTROL_URL.
$ GAMESTAGE_CONTROL_URL=https://formula1-dev.api.gamestage.ai \
gamestage admin workspace create --name "Formula 1" --owner py@formula1.com --org formula1
Team workspace created
Workspace ws_8c1d...
Name Formula 1
Owner py@formula1.com (takes it up on their next sign-in here)
Organisation formula1admin org list, admin org show and admin org set are how we set up a customer's organisation: which Studio it is on, its Studio organisation and spaces, the email domains that join it, its consent gate and its fans' sign-in. Each control plane keeps its own organisations, so the commands change the one the CLI is pointed at, and a customer can be on studio-dev in one and on their own Studio in another.
$ gamestage admin org set nba --studio-host us --studio-org 4b1f... --space 9c2e...
Organisation updated
Organisation nba
Studio Not set → us
Studio org 7ba0ec97-... → 4b1f...
Spaces 76d6efa5-... (default) → 9c2e... (default)
Decided by operator@monterosa.co.ukadmin org set creates the organisation if there is none, which needs --name, and otherwise changes only the fields you give and prints those, before and after. --studio-host is us, eu or dev. --space and --domain may be repeated and replace the list; the first space is where a deploy lands when nobody names one. --consent is onetrust or ours. --identity is the fans' sign-in reference, such as an Identify project. --signed-agreement records that the organisation's signed agreement with Monterosa covers Gamestage, so its workspaces are not asked to accept the click-through Terms, and the audit trail names the agreement when one of them deploys or is approved without accepting; --no-signed-agreement takes it away. --attio-company links the organisation to its company record in Attio: give the record id, or the company's address copied from Attio, and "" to remove the link. Gamestage stores the id and never reads Attio. --login-keys, --login-issuer, --login-audience and --login-claim set the fans' OpenID Connect sign-in that new games' logins are seeded from: its key set, the issuer and audience its tokens carry, and the claim the fan is in when it is not sub, such as SubscriberId. Give one empty, --login-issuer "", to remove it. They are refused on a sign-in of another kind, such as an Identify project. Setting what is already set prints "Nothing to do" and exits 0. An unknown option, a host or consent it does not know, a domain that already belongs to another organisation, or a new organisation with no name is refused and exits 1. admin org show prints every field, which Studio key the organisation's calls use (the shared service token, for now) and who last changed it. admin org list marks any organisation still read from the control plane's code rather than stored. Each change is recorded in the control plane's audit trail with who made it, and --json prints status (created, updated, unchanged or refused), before, after and, on a refusal, code.
admin trial and admin trials turn a plan limit from counting into refusing, one workspace and one limit at a time. Every limit counts and refuses nothing until its trial is on.
$ gamestage admin trial ws_01J9 day_cap on
Trial changed
Plays a day now refuses. It applies to each game on its next deploy, or within about a minute of a fan opening it.
Workspace ws_01J9
Plays a day Refuses
Monthly devices Counts, refuses nothing
Storage Counts, refuses nothing
Fair-use stop Refuses
Decided by operator@monterosa.co.uk| Limit | Off (the default) | On |
|---|---|---|
day_cap | A Starter game's plays past 100 a day are played and counted as over the limit. An Arcade game's runs past 5,000 a day are the same. | They are refused with capped_today, and an Arcade run with game_daily_limit_reached. Starter only: a paid plan has no daily limit, and Mystery has none on any plan. |
mau | Monthly devices past the plan's number are counted. | A deploy is refused with meter_breached. |
storage | Storage past the plan's number is counted. | A deploy is refused with meter_breached. |
fair_use | On a paid plan, a game at its fair-use limit keeps taking plays and we are alerted. | The game stops for 30 minutes. A Starter game always stops. |
day_cap and fair_use reach a game on its next deploy, or when a fan next opens it after the minute-long cooldown. mau and storage apply at the next deploy, which is what they refuse. Turning a trial on that is already on prints "Nothing to do" and exits 0. Each change is recorded in the workspace's audit trail with who made it. With --json, admin trial prints status (changed or unchanged), changed, limit, on, trials, effect and message; admin trials prints trials and effect.
admin features prints which plans carry Share cards and Comments, and every workspace with its own answer.
$ gamestage admin features
Plan services
Share cards Starter: off, Publisher: on, Enterprise: on
Comments Starter: off, Publisher: on, Enterprise: on
Workspace overrides
No workspace holds an override. Every workspace follows its plan.admin features set <plan> <service> on|off changes the plan setting, so admin features set starter sharing on puts Share cards on the Starter plan without a release. The plan is the id the API uses (runtime, live, enterprise) or the name a person reads (starter, publisher, enterprise). admin features <workspace> <service> on|off turns a service on or off for one workspace whatever its plan says, and plan clears the override so the workspace follows its plan again. admin features <workspace> prints that workspace's services and what each does now. A workspace in the Monterosa organisation is always allowed, whatever any switch says. Setting something to what it already is prints "Nothing to do" and exits 0. Each change is recorded with who made it: a workspace's change in its audit trail, a plan change on the record the control plane keeps. With --json, admin features prints services and overrides; admin features set prints status, changed, services, message and by; the workspace forms print status, changed, services, decision and message.
admin refresh sets how often one switched-on source, such as ESPN, is fetched for one workspace: a whole number of hours from 1 to 168, or default to go back to every 12 hours. It is how we answer a game that needs fresher numbers than twice a day.
admin source-on <workspace> fpl switches Fantasy Premier League on for a customer's workspace, the same as their own sources connect fpl, and records it in their audit trail as you. admin source-on <workspace> espn --league nba does the same for ESPN. It takes --measures and --name as sources connect does, and refuses a workspace id that does not exist.
admin domains lists every custom domain in every workspace, with its game, status and what DNS last said, which is how support answers "my domain is not working".
admin creator-sync refreshes the list we use to email creators about their application and Gamestage, now rather than on the hour, and prints only how many were updated.
admin erase, admin close and admin erasures are how we act on a written request to delete your data. To have one game's player data deleted, archive the game and write to us; admin erase deletes its plays, scores, leaderboards and player records. To leave, write to us; admin close takes every game off the air and deletes your games' player data, your games' files, your datasets and your account records. The audit trail of changes to your account and games is kept. Both finish within 30 days of the request, and usually at once. admin erasures lists what has been asked for, what is finished and when the rest is due.
If your account is waiting, nothing you type changes that. gamestage status re-checks it and says where you stand.
Exit codes
There are three exit codes.
| Code | Means |
|---|---|
0 | The command did what it said, or there was nothing to do. |
1 | It was refused or it failed. For verify, a check is open; for domain status, the domain failed; for prune, at least one record was refused (removed counts the rest). |
2 | verify could not prove something here. |
verify is where all three appear. It exits 0 only when every check verified, 1 when a check is open and the game failed verification, and 2 when no check failed but one was skipped, which leaves the result unverified. --no-browser therefore yields 2, because a skipped browser check leaves the rendered outcome unproved.
A refusal names its reason and carries a stable code in --json output: Starter turning down a second live game, or a deploy refused because GitHub is not linked, is the product working as designed, and it still exits 1. Branch on the code and fix the cause rather than retrying.