CLI reference

This page lists every gamestage command, what it does and what it leaves behind. It follows gamestage <command> --help, and where the two disagree the tool is correct.

This page writes every command as gamestage <command>. That is the form the shell installer puts on your PATH. Running from npm it is npx gamestage <command>, and running the downloaded bundle it is node gamestage.mjs <command>. gamestage start reports which form it is answering to.

--json is a global option and goes before the command: gamestage --json verify. Use it when a script or an agent will branch on the result instead of reading prose.

Commands marked "Needs sign-in" reach Backstage, so run login first. Signing in is public and self-serve, so a new account stops at approval instead: the commands answer access_pending until a person approves it.

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 the version it is, and reaches nothing over the network to do it. Read that number first when a command refuses something this page says it accepts: a cached bundle presents as a documentation error rather than as an old tool.

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 ..

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 it

If 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.

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 and shoot.

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.

dev

Serves your round locally, through the same Engine rules that serve it in the cloud. Prints window.GAMESTAGE_API and window.GAMESTAGE_GAME for the page. There is no watch mode: stop and restart after changing the container. Needs sign-in.

With no backend.round, which is the normal case because a game's rounds are written in Studio, dev plays a sample round for the game's format, the same one review plays, and says it is a sample. Nothing is written for it, so a deploy cannot publish it. With no readable manifest at all, dev serves the contract fixture and says so. The fixture is useful for wire work. It is not your game. --as mints a temporary keypair and loopback issuer; the manifest validator refuses that issuer in a deployed game.

verify

Runs the game against a real Engine and proves the migration is done. Needs sign-in. It runs a set of checks: whether the round played here is honestly this game's own, whether the attempt cap was chosen rather than defaulted, whether the answers are absent from everything a deploy would publish, 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.

review

Plays the built game against a local 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.html

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.

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.

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.

Pipe it in when it runs to more than one line. A newline inside a quoted argument ends the command at your shell, so a report typed across several lines arrives as its first line and nothing says so:

gamestage suggest --send < suggestion.txt

The 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.

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.

Pipe it in when it runs to more than one line. A newline inside a quoted argument ends the command at your shell, so a report typed across several lines arrives as its first line and nothing says so. That is how two real reports were lost. Write the report to a file, or pipe it from whatever wrote it:

gamestage issue --send < report.txt
type report.txt | gamestage issue --send    # Windows

The 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.

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.

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.

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

After a command you run by hand, the CLI checks npm at most once a day and, when a newer gamestage is out, prints one line saying so and how to update. It never checks for --json, a pipe, CI or GAMESTAGE_NO_UPDATE_CHECK=1.

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.

deploy <game>

Publishes a snapshot to a Playground, and the round it puts on. Needs sign-in.

--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. 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 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.

Without --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> [keys...]

Reports what a round would fail on, before a producer finds out by having one refused. 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 refuses the whole round rather than scoring as nothing, so one typo costs 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.

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 sources

For 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 sportmonks

Open 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.

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"

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.

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.

npx gamestage sources status sportmonks

sources 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.

npx gamestage sources disconnect sportmonks

round push <game>

Writes the round in your manifest into Studio, where a producer owns it from then on. Needs sign-in.

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 seed <game> --count <n>

Builds candidate rounds from the game's connected dataset, then creates one new element per round in its current Studio edition. Needs sign-in and a game that has been deployed with a dataset connected. Existing rounds are preserved; a producer reviews and publishes the new elements in Studio, where each is named and annotated like every other round. This does not publish them or refresh the Engine.

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

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.

graphic templates

Lists the screens a graphic can be cut for. No account needed, no network call.

gamestage graphic templates

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 --consent

On 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

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.

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 kickoff

Each 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-a7aeb8a7030f

A 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.

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.

gamestage graphic push kickoff --css graphic.css

Ready for a producer

  Game        Kick Off (kickoff)
  Stylesheet  graphic.css (3,204 of 10,000 characters)
  Address     https://<space-domain>/games/kickoff/graphic.css

Nothing is written to Live Graphics, and that is deliberate rather than a limitation we are working around. 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.

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.

endpoint <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.

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.

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 approve <workspace>, admin refuse <workspace>, admin plan <workspace> <plan>, admin refresh <workspace> <dataset> <hours>, admin creator-sync

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 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.

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 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.

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.

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.

Starter turning down a second live game, or a deploy refused because GitHub is not linked, is the product working as designed, so it exits 0 and carries a stable code in --json output. Branch on the code and fix the cause rather than retrying.