@opengamehq/cli 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/AGENTS.md +238 -0
  2. package/CHANGELOG.md +22 -0
  3. package/README.md +129 -2
  4. package/dist/cli.mjs +1432 -0
  5. package/dist/opengame-global.js +49 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +20 -0
  8. package/dist/runtime-builder.mjs +800 -0
  9. package/dist/runtime-catalog.json +1 -0
  10. package/dist/runtime-catalog.sha256 +1 -0
  11. package/dist/runtime-shells/runtime-shell.html +4 -0
  12. package/dist/runtime-shells/runtime-shell.js +91 -0
  13. package/dist/safe-fs.py +242 -0
  14. package/dist/skills/manifest.json +516 -0
  15. package/dist/skills/opengame-accessibility/SKILL.md +90 -0
  16. package/dist/skills/opengame-api/SKILL.md +85 -0
  17. package/dist/skills/opengame-assets/SKILL.md +124 -0
  18. package/dist/skills/opengame-assets/references/pipeline.md +97 -0
  19. package/dist/skills/opengame-audio/SKILL.md +154 -0
  20. package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
  21. package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
  22. package/dist/skills/opengame-capture/SKILL.md +108 -0
  23. package/dist/skills/opengame-capture/references/pipeline.md +82 -0
  24. package/dist/skills/opengame-capture/references/threejs.md +145 -0
  25. package/dist/skills/opengame-characters/SKILL.md +129 -0
  26. package/dist/skills/opengame-characters/references/integration.md +144 -0
  27. package/dist/skills/opengame-characters/references/player-og.md +160 -0
  28. package/dist/skills/opengame-cli/SKILL.md +118 -0
  29. package/dist/skills/opengame-deploy/SKILL.md +207 -0
  30. package/dist/skills/opengame-deploy/references/json-events.md +62 -0
  31. package/dist/skills/opengame-deploy/references/manifest.md +83 -0
  32. package/dist/skills/opengame-deploy/references/packaging.md +117 -0
  33. package/dist/skills/opengame-depth/SKILL.md +130 -0
  34. package/dist/skills/opengame-enemies/SKILL.md +103 -0
  35. package/dist/skills/opengame-enemies/references/threejs.md +134 -0
  36. package/dist/skills/opengame-front-end/SKILL.md +143 -0
  37. package/dist/skills/opengame-front-end/references/launch.md +50 -0
  38. package/dist/skills/opengame-front-end/references/menus.md +47 -0
  39. package/dist/skills/opengame-game-feel/SKILL.md +137 -0
  40. package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
  41. package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
  42. package/dist/skills/opengame-jam/SKILL.md +103 -0
  43. package/dist/skills/opengame-lighting/SKILL.md +94 -0
  44. package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
  45. package/dist/skills/opengame-loading/SKILL.md +99 -0
  46. package/dist/skills/opengame-loading/references/threejs.md +116 -0
  47. package/dist/skills/opengame-look/SKILL.md +114 -0
  48. package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
  49. package/dist/skills/opengame-mobile/SKILL.md +90 -0
  50. package/dist/skills/opengame-performance/SKILL.md +140 -0
  51. package/dist/skills/opengame-performance/references/measuring.md +72 -0
  52. package/dist/skills/opengame-production/SKILL.md +131 -0
  53. package/dist/skills/opengame-production/references/templates.md +63 -0
  54. package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
  55. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
  56. package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
  57. package/dist/skills/opengame-router/SKILL.md +51 -0
  58. package/dist/skills/opengame-router/references/process.md +38 -0
  59. package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
  60. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
  61. package/dist/skills/opengame-sdk/SKILL.md +270 -0
  62. package/dist/skills/opengame-sdk/references/engines.md +93 -0
  63. package/dist/skills/opengame-sdk/references/frame.md +107 -0
  64. package/dist/skills/opengame-sdk/references/identity.md +112 -0
  65. package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
  66. package/dist/skills/opengame-sdk/references/radio.md +71 -0
  67. package/dist/skills/opengame-stability/SKILL.md +84 -0
  68. package/dist/skills/opengame-verification/SKILL.md +136 -0
  69. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  70. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  71. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  72. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  73. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  74. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  75. package/package.json +38 -4
package/AGENTS.md ADDED
@@ -0,0 +1,238 @@
1
+ # OpenGame CLI: guidance for agents
2
+
3
+ How a coding agent deploys a creator's game with the `opengame` command. The command and exit code tables at the end are the CLI's own help; `opengame help --json` has every flag.
4
+
5
+ <!-- generated:procedure -->
6
+ Deploy the creator's game to a private preview, give them its link, and submit it only when they ask. Read each command's result before you run the next one.
7
+
8
+ ## Install
9
+
10
+ ```bash
11
+ npm i -g @opengamehq/cli
12
+ ```
13
+
14
+ Once `opengame` is installed, confirm it and read the command reference:
15
+
16
+ ```bash
17
+ opengame version --json
18
+ opengame help --json
19
+ ```
20
+
21
+ `help --json` lists every command, flag, exit code, environment variable and event, with the finding schema. Read it rather than guessing a flag.
22
+
23
+ Install the OpenGame skills for the agent you run in, from the game folder:
24
+
25
+ ```bash
26
+ opengame skills add .
27
+ ```
28
+
29
+ The CLI talks to `https://opengame.io`. Never put a token in a command argument, a file in the repository, a log or a reply. For CI, set `OPENGAME_TOKEN` or pipe the token with `--token-stdin`.
30
+
31
+ ## Output
32
+
33
+ Every command takes `--json`. When stdout is not a terminal, or `CI`, `CLAUDECODE` or another agent's variable is set, `--json` is the default. A command then prints one object:
34
+
35
+ ```json
36
+ {
37
+ "type": "result",
38
+ "command": "deploy",
39
+ "data": { "state": "queued", "done": false },
40
+ "ok": true,
41
+ "url": "https://opengame.io/settings/deployments/<id>",
42
+ "next": "opengame status --watch",
43
+ "findings": [],
44
+ "notices": []
45
+ }
46
+ ```
47
+
48
+ An error has `"type": "error"`, `"ok": false`, a `code`, a `message`, an `exitCode` and, when there is one, a `next` command to run. `--jsonl` streams one event per line instead: `progress`, `notice`, `finding`, then a `result` or `error` last. In either mode there are no prompts and no browser opens.
49
+
50
+ | Exit | Meaning | What to do |
51
+ | --- | --- | --- |
52
+ | 0 | Done | Read `data`. `data.done: false` means the server is still working. |
53
+ | 1 | The game needs a change | Fix each finding, then run its `verify` command. |
54
+ | 2 | The command needs input | Read the message. It names the missing flag or choice. |
55
+ | 3 | Sign in, or a token with the right scope | Run `next` when the error has one. |
56
+ | 4 | An allowance is used up | Wait `retryAfterSeconds`, then run the same command. |
57
+ | 5 | Our side or the network | Leave the game as it is. Run `next` when the error has one; otherwise wait and retry, at most a few times. |
58
+ | 6 | The CLI is too old | Run `opengame upgrade --json`, then the npm command in `data.command`. |
59
+ | 7 | OpenGame is not open to creators yet | Stop. Tell the creator the CLI and uploads open on 18 November. |
60
+
61
+ ## Sign in with the creator
62
+
63
+ ```bash
64
+ opengame whoami --json
65
+ ```
66
+
67
+ Exit 0 means a saved login works. Exit 3 means start one:
68
+
69
+ ```bash
70
+ opengame login --json
71
+ ```
72
+
73
+ `login --json` prints the approval link and code as a `device_approval` notice, then exits 3 with `login_pending`. Give the creator both. They open the link, sign in, type the code and press Allow access. You cannot approve it for them. When they say they have, finish:
74
+
75
+ ```bash
76
+ opengame login --continue --json
77
+ ```
78
+
79
+ `--continue` waits up to 10 seconds for the approval.
80
+
81
+ | Result | What to do |
82
+ | --- | --- |
83
+ | Exit 0 | Signed in. `data.handle` is the creator's handle. |
84
+ | Exit 3, `login_pending` | Not approved yet. Run `login --continue --json` again once the creator has pressed Allow access. |
85
+ | Exit 3, `access_denied` | The creator pressed Deny, or the account cannot be used. Read the message to them. |
86
+ | `login_expired` or `no_pending_login` | The code ran out. Run `login --json` for a new one. |
87
+
88
+ ## Deploy a private preview
89
+
90
+ Run these from the game folder.
91
+
92
+ If the folder has no `opengame.json`, create one. Ask the creator whether it is a game, a world, a decomp or a mod; a decomp or a mod names the game it is based on:
93
+
94
+ ```bash
95
+ opengame init . --title "My game" --json
96
+ opengame init . --title "Doom but blue" --kind mod --based-on "Doom" --json
97
+ ```
98
+
99
+ Then fill in `description` (40 characters or more) and `genre` in `opengame.json`. If the file already exists, leave `init` alone and edit the file.
100
+
101
+ For a game that already exists on OpenGame, in a new checkout, link the folder first so the deploy does not create a second game:
102
+
103
+ ```bash
104
+ opengame games --json
105
+ opengame link --game <id> --json
106
+ ```
107
+
108
+ Check, then deploy:
109
+
110
+ ```bash
111
+ opengame check . --build --json
112
+ opengame deploy . --json
113
+ ```
114
+
115
+ `deploy` runs the manifest's build command, checks the output and uploads it, up to 1 GiB zipped. It returns once the upload is in, with exit 0 and `data.done: false`, while the checks run on the server. Keep `.opengame/`: later commands resume and follow the same deploy from it. Use `--no-build` only when the creator says the export is already built and its build cannot run here, never to get past a failing build.
116
+
117
+ | Field | What it holds |
118
+ | --- | --- |
119
+ | `data.deploymentUrl` | The deploy's page. Give it to the creator straight away: it shows each check and plays the preview once they pass. |
120
+ | `data.state` | `uploading`, `queued`, `checking`, `ready`, `failed` or `expired`. |
121
+ | `data.done` | `true` once the server has finished. |
122
+ | `data.releaseId` | The release. Keep it for `submit`. |
123
+ | `data.previewUrl` | The private preview link, once `state` is `ready`. It can be `null` on a ready release the server will not play; the deploy's page says why. |
124
+ | `data.gameOrigin` | The origin the published game runs at, such as `https://k3v9q2m7x4ab.opengame.gg`. Give it to the creator when the game talks to their own servers. `null` when the server sent none, or sent one this CLI cannot read. |
125
+
126
+ To follow the checks, run `status --watch`, which follows the deploy for up to 5 minutes. Set `--timeout <seconds>` for a short tool call; when it runs out the command exits 5 with `checks_pending` and the checks carry on.
127
+
128
+ ```bash
129
+ opengame status --watch --timeout 60 --json
130
+ ```
131
+
132
+ To block on the outcome in one command, deploy with `--wait`:
133
+
134
+ ```bash
135
+ opengame deploy . --wait --json
136
+ ```
137
+
138
+ Tell the creator the preview is ready only when a result says `data.state: "ready"` and `data.done: true`. Give them `data.previewUrl` and `data.releaseId`. Play it, or ask them to, before you say the game works.
139
+
140
+ ## Fix findings
141
+
142
+ Each finding has a `fault`, a `certainty` and a `retry`:
143
+
144
+ | Finding | What to do |
145
+ | --- | --- |
146
+ | `fault: game` | Read `evidence`, make the change in `fix`, then run the command in `verify`. |
147
+ | `certainty: heuristic` | Check the evidence before you change working code. |
148
+ | `fault: platform` | Leave the game as it is. Follow `retry`: `now` runs again, `later` waits `retryAfterSeconds`, `after-fix` and `never` mean waiting will not help, so read `fix`. |
149
+ | `fault: unknown` | A person decides at review. Report it to the creator. |
150
+
151
+ A plain `deploy` resumes a saved upload, or starts a fresh one with an `upload_restarted` notice when the saved one can no longer finish. A deploy started with `--idempotency-key` exits 2 instead. Start a fresh one with a new key, or without the flag:
152
+
153
+ ```bash
154
+ opengame deploy . \
155
+ --idempotency-key <a new key> --json
156
+ ```
157
+
158
+ Before a large batch of deploys, run `opengame limits --json` for the upload limits and the allowance left on the account. If the same platform failure repeats, stop and give the creator the command, the error code and the evidence.
159
+
160
+ ## Submit only on request
161
+
162
+ A deploy makes a private preview that only the creator's account can open. `opengame submit` sends a release to review, and the game goes public once review approves it and it is published. Submit only when the creator asks, and send the exact `releaseId` they played.
163
+
164
+ ```bash
165
+ opengame jams --json
166
+ opengame submit --release <releaseId> --no-wait --json
167
+ ```
168
+
169
+ OpenGame decides where submissions go. When that is a jam, the submission is the creator's entry: read the form with `opengame jams <slug> --json`, ask the creator for their track, the models they used and any sponsor evidence, and pass them as `--track`, `--models`, `--sponsor` and `--evidence-<sponsor>`. A missing answer exits 2 and names the flag. A decomp or a mod cannot enter a jam.
170
+
171
+ When `data.state` is `needs_certification`, give the creator `data.certifyUrl`, which the CLI also prints as a `certify_required` notice. They certify in their own browser that they have the rights to the game. You cannot do it for them. Follow the review with:
172
+
173
+ ```bash
174
+ opengame status --watch --json
175
+ ```
176
+
177
+ ## What a game may do
178
+
179
+ OpenGame hosts static browser exports. The build needs `index.html` at the root of its output folder.
180
+
181
+ At runtime the game may call its own origin, `https://api.opengame.gg`, and any other `https:` or `wss:` host. Each call comes from the player's browser, so that host sees the player's IP address. Keep API keys on the creator's server, never in the bundle: players can read every file in it. The review sandbox has no internet, so the game must draw its first frame without its server.
182
+
183
+ The published game runs at `https://<label>.opengame.gg`, one origin per game, and `opengame deploy` returns it as `data.gameOrigin`. While an experiment runs, players load each version taking part from a `v-` origin instead. If the creator's servers check `Origin` (WebSocket) or send CORS headers (HTTP), they reject the game's requests until that exact origin is on their list, and online play fails with a closed socket, a 401 or 403 on the upgrade, or a CORS error in the console. Tell the creator to add it, and to add a version's `v-` origin before starting an experiment with it. Never suggest allowing `*.opengame.gg`, `null` or any pattern on `opengame.gg`, because other people's games are served there too and a pattern lets them call the creator's server. Use a token in a header or the first socket message, not a cookie. A private preview runs on a temporary `p-` origin, not the game's. That address is a private link, so keep it out of committed config and logs. [Games that talk to your own servers](https://docs.opengame.io/guides/packaging#games-that-talk-to-your-own-servers) has server examples.
184
+
185
+ A game may not take payments, use crypto, make players create an account or give an email address, show ads, or carry ad pixels or session recording. [Packaging](https://docs.opengame.io/guides/packaging) has every rule and every check.
186
+
187
+ ## Engines
188
+
189
+ OpenGame supports games built with Three.js, Unity, Godot, Kaigen and WebAssembly, and static web builds from any JavaScript engine. `opengame check` and the server detect the engine from the build. Any other static browser export uploads as a custom build, under the same file, scan and runtime checks.
190
+
191
+ Run `opengame init . --engine <id>` to record an engine's export folder. `opengame help --json` lists the IDs, and `init` prints the export steps and the guide for the one you choose. The [engine overview](https://docs.opengame.io/engines/overview) links every engine page.
192
+
193
+ Play the private preview before you tell the creator the game works.
194
+ <!-- /generated:procedure -->
195
+
196
+ ## Where it runs
197
+
198
+ `dev`, `vendor`, `check --vendor`, `deploy --vendor` and Unity asset uploads need Python 3 on macOS or Linux: they read files with a small Python helper that opens each one relative to a held directory, so a symlink swapped into the path mid-read cannot send it outside the project. The CLI looks for Python 3 at `/usr/bin/python3`, `/opt/homebrew/bin/python3`, `/usr/local/bin/python3` and `/bin/python3`, never through `PATH`; without one those commands stop with `filesystem_unsupported` before reading anything, and the fix is to install Python 3 from python.org or Homebrew. Plain `check` and `deploy` use the same helper when Python is found and otherwise read with a Node fallback, after a `node_reader_fallback` notice; they work either way.
199
+
200
+ ## Commands and exit codes
201
+
202
+ <!-- generated:commands -->
203
+ | Command | What it does |
204
+ | --- | --- |
205
+ | `opengame init [dir] [options]` | Create opengame.json for an existing game. |
206
+ | `opengame check [dir] [options]` | Find local build and asset problems before uploading. |
207
+ | `opengame dev [dir] [options]` | Serve a local export with game-runtime headers. Under a contract that adds the SDK, pages also get the host runtime and SDK, as they do when hosted. If the contract supports opting out, sdk.inject: false leaves out the SDK. |
208
+ | `opengame login [options]` | Sign in through your browser. |
209
+ | `opengame deploy [dir] [options]` | Build, check and upload a release, then return with the address of its deployment page, where the checks run and the private preview plays once they pass. Add --wait to stay until they finish. Once the preview is ready, the achievements opengame.json declares are saved by deploy --wait or by the next opengame status in this folder. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
210
+ | `opengame status [dir] [options]` | Show the most recent deploy for this folder, with its findings. Finishes saving its declared achievements if the deploy could not. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
211
+ | `opengame deployments [dir] [options]` | List the linked game's deploys, newest first: status, when, size, who started each one, why any stopped, and each one's page or preview. |
212
+ | `opengame open [dir] [options]` | Open the linked game's private page in your browser. |
213
+ | `opengame submit [dir] [options]` | Send one release to review, and enter it in a jam. |
214
+ | `opengame jams [slug] [options]` | List open jams, or show one jam's tracks and flags. |
215
+ | `opengame games [options]` | List your games and their latest deploy. |
216
+ | `opengame link [dir] [options]` | Connect this folder to an existing game. |
217
+ | `opengame pull [dir] [options]` | Bring website metadata into this folder. |
218
+ | `opengame stats [game\|dir] [options]` | Read analytics for a game you own, or this folder's linked game, for one complete ISO week, Monday to Sunday in UTC. Average playtime is total playtime divided by distinct players in the week. |
219
+ | `opengame whoami [options]` | Show the account and permissions for this token. |
220
+ | `opengame token create\|list\|revoke [options]` | Create, list or revoke tokens in your browser. |
221
+ | `opengame logout [options]` | Revoke this device's token and remove it locally. |
222
+ | `opengame limits [options]` | Show bundle limits and your remaining account allowance. |
223
+ | `opengame vendor [dir] [options]` | Create a separate export with dependencies downloaded at their exact versions, rewritten and hashed. |
224
+ | `opengame skills add\|list [dir] [options]` | Install the OpenGame skills for your coding agent. |
225
+ | `opengame upgrade [options]` | Install the current CLI, or print the line that does. |
226
+ | `opengame version [options]` | Print the CLI version. |
227
+
228
+ | Exit | Name | Meaning |
229
+ | --- | --- | --- |
230
+ | 0 | `ok` | Done. With done:false in the result, the deploy is still running on our side: open data.url to watch it, or follow it with opengame status --watch. |
231
+ | 1 | `check` | The game needs a change. Read the finding events, or the error's finding and message when there are none, fix it, then run the finding's verify command. |
232
+ | 2 | `input` | The command needs input: a flag, a choice or a different command. The message names it. With retry never, running the same command again cannot help. |
233
+ | 3 | `auth` | Sign in, or use a token with the right scope. Run the error's next command when it has one. With retry never, signing in again will not help: the account itself has no access. |
234
+ | 4 | `rateLimited` | An allowance is used. Wait retryAfterSeconds when the error has it, then run the same command. |
235
+ | 5 | `server` | Our side or the network, and the game is fine. Run the error's next command when it has one. With retry after-fix or never, waiting will not help; read the message. Otherwise wait (retryAfterSeconds when given) and run the same command. |
236
+ | 6 | `upgrade` | This CLI is too old. Run opengame upgrade. |
237
+ | 7 | `notLaunched` | OpenGame is not open to creators yet, so nothing ran. The message names the day the CLI and uploads open. Nothing about the game, the command or the login is wrong. Retrying will not help before then. |
238
+ <!-- /generated:commands -->
package/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ ## 0.5.0
4
+
5
+ - Before OpenGame opens for creators, a refused command names the day it opens ("OpenGame
6
+ opens for creators on 18 November") rather than saying it is not launched.
7
+ - `opengame deploy` returns `gameOrigin`, the origin the published game runs at, and says
8
+ to allow that exact origin when the game's own servers check `Origin` or send CORS
9
+ headers.
10
+ - `opengame pull` names the website setting opengame.json cannot hold, such as a player
11
+ count it has no room for, and the way past it, rather than a general manifest error.
12
+ - `--help --json` no longer carries `internal: true`, and the local checker's failure no
13
+ longer tells you to reinstall an internal CLI.
14
+ - Ships the skills from `@opengamehq/skills` 1.1.0.
15
+
16
+ ## 0.4.0
17
+
18
+ - First release on npm. This version is published by hand and has no npm provenance
19
+ statement; versions published from this repository's workflow will.
20
+ - Add the launch check and the `not_launched` exit code (7): when OpenGame has not opened
21
+ for the account, a command that needs it says so and stops.
22
+ - `AGENTS.md` is in the package: the procedure a coding agent follows to deploy a game.
package/README.md CHANGED
@@ -1,3 +1,130 @@
1
- # Temporary Holding Version
1
+ # @opengamehq/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Deploy browser games to [OpenGame](https://opengame.io) from your terminal. The `opengame`
4
+ command checks a game folder, uploads it and gives you a private preview to play.
5
+
6
+ ## Install
7
+
8
+ <!-- install:cli -->
9
+ ```bash
10
+ npm i -g @opengamehq/cli
11
+ ```
12
+ <!-- /install -->
13
+
14
+ It needs Node.js 18.17 or later. `opengame --version` prints the version you have.
15
+
16
+ ## Sign in
17
+
18
+ ```bash
19
+ opengame login
20
+ ```
21
+
22
+ Your browser opens on opengame.io. Sign in with Google or an emailed code and press
23
+ Allow access. The CLI keeps the token in the macOS Keychain, and elsewhere in a private
24
+ file under `~/.config/opengame`. In CI, pass a token through `OPENGAME_TOKEN` or
25
+ `--token-stdin`, never as a command argument.
26
+
27
+ When OpenGame has not opened to creators for your account, a command that needs the
28
+ platform prints `OpenGame opens for creators on` the day the CLI and uploads open, and exits
29
+ with code 7. Signing in works either way.
30
+
31
+ ## Deploy a game
32
+
33
+ Run these from the folder that holds your game's `index.html`, or its source when the
34
+ build writes one.
35
+
36
+ ```bash
37
+ opengame init .
38
+ opengame check .
39
+ opengame deploy .
40
+ ```
41
+
42
+ `init` writes `opengame.json`, the manifest with your game's title, description and
43
+ build. `check` runs the same checks the upload will, on your machine. `deploy` builds,
44
+ checks and uploads a release, then prints its deployment page:
45
+
46
+ ```
47
+ Uploaded. The checks run on our side, so you can close this terminal.
48
+ Your upload is queued for checks.
49
+ Watch them, and play the preview once it is ready, at https://opengame.io/settings/deployments/<id>
50
+ Or follow them here with opengame status --watch.
51
+ ```
52
+
53
+ The private preview plays on that page once the checks pass. Add `--wait` to stay in the
54
+ terminal until they finish. When the preview is ready, `opengame submit` sends the
55
+ release to review.
56
+
57
+ ## Scripts and agents
58
+
59
+ Every command takes `--json` and prints one result object. For `deploy`:
60
+
61
+ ```json
62
+ {
63
+ "type": "result",
64
+ "command": "deploy",
65
+ "ok": true,
66
+ "data": { "operationId": "<id>", "done": false, "deploymentUrl": "https://opengame.io/settings/deployments/<id>" },
67
+ "url": "https://opengame.io/settings/deployments/<id>",
68
+ "next": "opengame status --watch",
69
+ "findings": [],
70
+ "notices": []
71
+ }
72
+ ```
73
+
74
+ A failure prints `"type": "error"` with `ok: false`, a `code` such as `not_launched`, a
75
+ `message` and the process exits with a non-zero code. `opengame help --json`
76
+ lists every command, flag, error code and exit code. `--jsonl` streams progress events.
77
+
78
+ `opengame skills add .` installs the OpenGame skills for Claude Code, Codex, Cursor or
79
+ OpenCode, so a coding agent can do all of the above for you.
80
+
81
+ ## Commands
82
+
83
+ <!-- generated:commands -->
84
+ | Command | What it does |
85
+ | --- | --- |
86
+ | `opengame init [dir] [options]` | Create opengame.json for an existing game. |
87
+ | `opengame check [dir] [options]` | Find local build and asset problems before uploading. |
88
+ | `opengame dev [dir] [options]` | Serve a local export with game-runtime headers. Under a contract that adds the SDK, pages also get the host runtime and SDK, as they do when hosted. If the contract supports opting out, sdk.inject: false leaves out the SDK. |
89
+ | `opengame login [options]` | Sign in through your browser. |
90
+ | `opengame deploy [dir] [options]` | Build, check and upload a release, then return with the address of its deployment page, where the checks run and the private preview plays once they pass. Add --wait to stay until they finish. Once the preview is ready, the achievements opengame.json declares are saved by deploy --wait or by the next opengame status in this folder. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
91
+ | `opengame status [dir] [options]` | Show the most recent deploy for this folder, with its findings. Finishes saving its declared achievements if the deploy could not. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
92
+ | `opengame deployments [dir] [options]` | List the linked game's deploys, newest first: status, when, size, who started each one, why any stopped, and each one's page or preview. |
93
+ | `opengame open [dir] [options]` | Open the linked game's private page in your browser. |
94
+ | `opengame submit [dir] [options]` | Send one release to review, and enter it in a jam. |
95
+ | `opengame jams [slug] [options]` | List open jams, or show one jam's tracks and flags. |
96
+ | `opengame games [options]` | List your games and their latest deploy. |
97
+ | `opengame link [dir] [options]` | Connect this folder to an existing game. |
98
+ | `opengame pull [dir] [options]` | Bring website metadata into this folder. |
99
+ | `opengame stats [game\|dir] [options]` | Read analytics for a game you own, or this folder's linked game, for one complete ISO week, Monday to Sunday in UTC. Average playtime is total playtime divided by distinct players in the week. |
100
+ | `opengame whoami [options]` | Show the account and permissions for this token. |
101
+ | `opengame token create\|list\|revoke [options]` | Create, list or revoke tokens in your browser. |
102
+ | `opengame logout [options]` | Revoke this device's token and remove it locally. |
103
+ | `opengame limits [options]` | Show bundle limits and your remaining account allowance. |
104
+ | `opengame vendor [dir] [options]` | Create a separate export with dependencies downloaded at their exact versions, rewritten and hashed. |
105
+ | `opengame skills add\|list [dir] [options]` | Install the OpenGame skills for your coding agent. |
106
+ | `opengame upgrade [options]` | Install the current CLI, or print the line that does. |
107
+ | `opengame version [options]` | Print the CLI version. |
108
+
109
+ | Exit | Name | Meaning |
110
+ | --- | --- | --- |
111
+ | 0 | `ok` | Done. With done:false in the result, the deploy is still running on our side: open data.url to watch it, or follow it with opengame status --watch. |
112
+ | 1 | `check` | The game needs a change. Read the finding events, or the error's finding and message when there are none, fix it, then run the finding's verify command. |
113
+ | 2 | `input` | The command needs input: a flag, a choice or a different command. The message names it. With retry never, running the same command again cannot help. |
114
+ | 3 | `auth` | Sign in, or use a token with the right scope. Run the error's next command when it has one. With retry never, signing in again will not help: the account itself has no access. |
115
+ | 4 | `rateLimited` | An allowance is used. Wait retryAfterSeconds when the error has it, then run the same command. |
116
+ | 5 | `server` | Our side or the network, and the game is fine. Run the error's next command when it has one. With retry after-fix or never, waiting will not help; read the message. Otherwise wait (retryAfterSeconds when given) and run the same command. |
117
+ | 6 | `upgrade` | This CLI is too old. Run opengame upgrade. |
118
+ | 7 | `notLaunched` | OpenGame is not open to creators yet, so nothing ran. The message names the day the CLI and uploads open. Nothing about the game, the command or the login is wrong. Retrying will not help before then. |
119
+ <!-- /generated:commands -->
120
+
121
+ `opengame <command> --help` prints that command's flags and examples.
122
+
123
+ ## Documentation
124
+
125
+ The full guide, the API reference and the limits are at
126
+ [docs.opengame.io](https://docs.opengame.io).
127
+
128
+ ## License
129
+
130
+ Apache-2.0