How to Use GameMaker GM-CLI with Claude Code - First Terminal Agent Evening 2026

If you are searching gamemaker gm-cli, you do not need another Unity CLI essay. You need a Monday path: install Node, run @gamemaker/gm-cli via npx, init or open a throwaway project, prove compile / run, decide how Claude Code is allowed (opt-in, not silent), and file keep or hold before any agent or GitHub Action touches a shipping branch.

On April 30, 2026, Opera’s GameMaker newsroom announced GMRT (new GameMaker Runtime) alongside GM-CLI—a command-line toolchain that works with both the new and existing runtimes—and Claude Code in that CLI so developers can query projects, hunt bugs, and manage builds through natural language in the terminal.Opera Newsroom Game Developer The live package path is npm’s @gamemaker/gm-cli (2.2.0 line as of Jun 5, 2026) and the public YoYoGames/gm-cli repo.

Who this is for: GameMaker creators who want terminal CI and agent workflows; beginners who only ever clicked the IDE; leads who need governance language for “Claude can edit our .yyp tree.”
Time: 90–150 minutes for a first agent-safe smoke on a branch or throwaway project.
Honest limit: Claude Code in GM-CLI is opt-in tooling, not a mandatory IDE rewrite. Russell Kay’s framing to Game Developer: complementary tools, no embedded AI servers required to keep shipping without them.Game Developer

Non-repetition: This is not the Unity CLI agent-safe evening (Unity unity binary + Pipeline). It is not GameMaker Photon multiplayer or Discord Social SDK Rich Presence. It is not Cyberpunk Fest themed-sale ops. Same “first evening keep/hold” discipline—different binary.

Why this matters now

1. Terminal is where agents and CI already live. Opera’s GMRT launch positions GM-CLI as the path to work without touching the IDE, with plain-text project files that track properly in Git and plug into automated builds.Opera Newsroom
2. Claude Code is in the official toolchain—not a random Discord bot. GameMaker bundled Anthropic’s agent into the CLI story so natural-language prompts can query structure, debug, and manage build configuration—while remaining opt-in.Game Developer
3. SERP is announcement-heavy. Press and npm README cover install flags; they do not ship an indie G1–G6 keep/hold that separates guest license smoke from access keys, AGENTS.md/MCP forward holds, and Unity CLI cousin confusion.

Parent demand under GameMaker stays large (SiteStatsDB-class snapshots put gamemaker.io around ~193K monthly organic visitors). The official npm package shows ongoing install activity (npm-class weekly downloads in the mid-hundreds for @gamemaker/gm-cli)—independent proof that people are actually installing the CLI, not only reading the press release.

What GM-CLI is (and is not)

Opera’s release notes: GM-CLI works with both the new and existing runtimes; Claude Code sits in the CLI so you can describe what you want to build, test, iterate, or ship.Opera Newsroom

Prerequisites

Confirm every line before you paste npx into a machine that also holds Steamworks and Discord secrets.

• [ ] Node.js with npm / npx (required by the official CLI README).gm-cli
• [ ] Terminal you control (Windows PowerShell, macOS Terminal, or Linux shell)—not a shared kiosk.
• [ ] Disk space for runtime/toolchain downloads the CLI may fetch on first compile/run.
• [ ] A throwaway project or git branch—never first-smoke on main of a live Steam title.
• [ ] Named session owner who files the receipt.
• [ ] Written agent policy: Claude/MCP off until G1–G4 pass; secrets never in chat transcripts.

If you only want the IDE forever, you can skip this evening. If you want CI, plain-text Git, or opt-in Claude in the terminal, continue.

For IDE literacy before CLI, use the GameMaker Studio guide hub.

Beginner path - first evening without an agent

Step 1 - Confirm Node, then invoke the CLI

Official pattern from YoYoGames:

npx @gamemaker/gm-cli@latest --help

Or install globally if you prefer a short command:

npm install -g @gamemaker/gm-cli@latest
gm-cli --help

Pin a version in CI later (@2.2.0 style)—tonight @latest is fine for learning, then record the exact version in the receipt.npm package

Step 2 - Create or open a throwaway project

npx @gamemaker/gm-cli@latest init

Follow prompts for blank game or template. If you already have a project, cd into it and skip init. Prefer a disposable folder named something like gm-cli-smoke-2026 so nobody mistakes it for shipping content.

Step 3 - Guest license honesty

The CLI docs note it can give you a guest license so you do not need to sign in for basic work—and that you may prefer your own access key from GameMaker account settings when you want owned licensing.gm-cli README

Tonight:

1. Try the default guest path for compile/run smoke.
2. If guest fails or policy requires named seats, create/access an access key from GameMaker access keys and configure per --help / auth commands—never commit keys to git.

Step 4 - Human compile and run smoke

From the project directory:

npx @gamemaker/gm-cli@latest compile --help
npx @gamemaker/gm-cli@latest compile
npx @gamemaker/gm-cli@latest run

Use --help on each command to see target, runtime, and toolchain options before you invent flags from memory.gm-cli

Pass criteria for tonight’s human smoke:

• Compile exits successfully (or fails with a readable project error you can fix).
• Run launches the expected window/player for your target.
• You can point to the git commit (or folder snapshot) that produced the smoke.

Do not enable Claude until this human path is green.

Step 5 - Optional Claude Code smoke (still gated)

Only after G1–G4:

1. Confirm Claude Code is available through the CLI surface your install exposes (opt-in—not silent).Game Developer
2. Give a read-only style prompt first: “List top-level project structure” / “Summarize build config files”—not “rewrite netcode.”
3. Review any file diffs in git before accepting.
4. Re-run compile after agent edits.

If Anthropic/Claude auth is required on your machine, store credentials outside the repo. Treat agent transcripts as untrusted logs—they can leak paths and keys.

Step 6 - File the evening receipt

Write six lines before you close the laptop:

1. Node version + @gamemaker/gm-cli version.
2. Guest vs access-key path used.
3. Commands that passed (compile / run).
4. Claude used? yes/no + prompt scope.
5. Pass/fail on G1–G6.
6. Keep or hold for MCP/CI.

Developer path - gates, hygiene, and honest limits

G1–G6 keep/hold gates

Latch gm_cli_terminal_ok only when G1–G6 pass. Do not latch on “npx downloaded something” alone.

Sample receipt JSON

{
  "schema": "gamemaker_gm_cli_receipt_v1",
  "session_date": "2026-07-24",
  "node_version": "20.x",
  "gm_cli_version": "2.2.0",
  "license_path": "guest",
  "project": "gm-cli-smoke-2026",
  "commands": {
    "help_ok": true,
    "compile_ok": true,
    "run_ok": true
  },
  "claude_code_used": false,
  "mcp_enabled": false,
  "gates": {
    "G1": true,
    "G2": true,
    "G3": true,
    "G4": true,
    "G5": true,
    "G6": true
  },
  "gm_cli_terminal_ok": true,
  "next_hold": ["agents_md", "mcp_server", "github_actions_compile"]
}

GM-CLI vs Unity CLI vs IDE (pick jobs)

AGENTS.md, MCP, and Claude config (forward hold)

The gm-cli docs call out AI agent integration via AGENTS.md, MCP, and Claude config as intended surfaces.gm-cli Treat them as second evening work:

1. Human compile/run green.
2. Written allowlist of files agents may touch.
3. Branch protection on main.
4. Then add AGENTS.md / MCP with least privilege.

Do not paste a Unity MCP mcp.json into a GameMaker repo and expect it to work.

GitHub Actions sketch (after G1–G6)

Conceptual job (adapt to your org’s Node cache and secrets store):

# sketch only — verify against current gm-cli help before shipping
jobs:
  gm-compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx @gamemaker/[email protected] compile
        # inject access key via secrets if guest is insufficient

Pin the CLI version. Never echo access keys in logs. Fail the job on non-zero exit codes.

Company / diligence notes

Partners will ask:

1. Is AI required to use GameMaker? No—CLI Claude is opt-in; IDE workflows remain valid.Game Developer
2. What data leaves the machine? Document Claude/Anthropic usage separately from guest compile; do not imply “local only” if prompts go to a cloud model.
3. Who can enable agents? Named owners + G1–G6 before MCP.
4. CI licensing? Guest vs access-key policy written; keys in secret stores only.
5. GMRT migration? Separate roadmap decision—do not block terminal smoke on full runtime cutover.Opera Newsroom

Common mistakes (and the fix)

1. Copying Unity CLI install curls — wrong binary. Use npx @gamemaker/gm-cli@latest.
2. Skipping Node — CLI requires npm/npx.gm-cli
3. Agent-first, compile-never — establish human baseline first.
4. Committing access keys — rotate immediately; use secrets managers.
5. Assuming Claude is always on — leadership framing is opt-in.Game Developer
6. Mixing Photon/Discord evenings into the same receipt — separate stacks, separate gates.
7. Unpinning @latest in CI — pin versions for reproducibility.
8. Running first smoke on the live Steam depot project — use throwaway or branch.

Prompt templates (Claude on, after G4)

Use these only on a throwaway branch. Paste results into the receipt.

Read-only structure

List the top-level files and folders in this GameMaker project. Do not modify any files. Flag anything that looks like secrets (keys, tokens, .env).

Build config summary

Summarize how this project is configured to compile for Windows desktop. Quote file names you relied on. Do not edit files.

Supervised fix (only after read-only worked)

The last gm-cli compile failed with this error: …paste… Propose the smallest fix. Show the exact file paths and diffs. Wait for my approval before writing.

Reject prompts like “make the whole game multiplayer” or “add Discord + Photon tonight.” Those belong in their own evenings.

Platform and toolchain notes

Package and publish surfaces (hold until compile is boring)

The CLI also documents packaging and related publish helpers (including gx.games-oriented commands in the README family). Treat package and store uploads as after G1–G6 and after your Steam/itch evening playbooks—not as the same night as first npx --help.gm-cli Pair Steam export with demo export sanity when that is the real job.

Risk matrix for enabling Claude

Troubleshooting

npx cannot find package / network error
Fix Node install, proxy, or registry allowlist for registry.npmjs.org. Corporate mirrors must permit @gamemaker/gm-cli.

--help works but compile downloads forever
Expect first-run toolchain fetch. Check disk space and firewall. Do not cancel mid-download and assume corruption without retrying once.

Compile fails with project errors
That is progress—CLI is honest. Fix GML/assets in IDE or with a supervised Claude prompt, then recompile. Do not blame Node.

Guest license insufficient
Move to access keys; never paste keys into Discord. Re-run auth per current CLI help.

Claude available but “does nothing useful”
Confirm opt-in/auth for the agent surface; start with read-only prompts; verify you are in the project directory the agent can see.

IDE and CLI fight over files
Use separate clones or close the IDE during CLI agent writes.

Sample evening timeline (strict)

When to hold (do not force keep)

Hold Claude/MCP/CI if:

• Compile fails for project reasons you do not understand yet.
• Corporate npm registry blocks @gamemaker/gm-cli.
• Legal has not approved cloud LLM prompts on proprietary GML.
• You are mid–Steam setlive and cannot risk toolchain downloads tonight.

Keep GM-CLI for human compile/run if G1–G4 pass even when Claude stays off.

Forward path after a green evening

1. Pin CLI version in a package.json script or CI pin.
2. Add a weekly compile Action on PRs.
3. Author AGENTS.md with file allowlists.
4. Revisit GMRT language roadmap (JS/TS/C#) as a separate migration playbook.Opera Newsroom
5. Only then expand Claude from read-only to supervised write prompts.

Key takeaways

1. gamemaker gm-cli in 2026 means official @gamemaker/gm-cli on npm—not a Unity binary.
2. Opera’s Apr 30 launch paired GMRT + GM-CLI + Claude Code; Claude remains opt-in.
3. Start with Node + npx @gamemaker/gm-cli@latest --help.
4. Prove human compile / run before any agent writes files.
5. Guest license can unblock first smoke; access keys stay out of git.
6. File G1–G6 before enabling AGENTS.md/MCP.
7. Pin versions in CI; do not rely on @latest forever.
8. Do not confuse GM-CLI with Unity CLI, Photon rooms, or Discord Social SDK.
9. Plain-text projects + Git are part of the GMRT/CLI story—use branches.
10. Document LLM data handling separately from local compile success.
11. Hold agents during Steam upload weeks unless G1–G6 already green.
12. Cite Opera newsroom + Game Developer + npm/GitHub when partners ask what changed.

FAQ

Do I need Claude Code to use GM-CLI?

No. You can install and run compile / run / package without enabling AI. Claude is positioned as an opt-in workflow inside the CLI story.Game Developer

How do I install GameMaker GM-CLI?

Install Node, then npx @gamemaker/gm-cli@latest --help, or npm install -g @gamemaker/gm-cli@latest.gm-cli

Is a GameMaker IDE license required tonight?

The CLI documents a guest license path for getting started, with optional access keys for owned licensing. Confirm your studio policy before CI at scale.gm-cli README

How is this different from Unity CLI?

Different engine, different package, different flags. Unity’s path is covered in How to Use Unity CLI - First Agent Safe Editor Session 2026. Do not mix install scripts.

Does GM-CLI replace the GameMaker IDE?

No. It complements the IDE for terminal, CI, and agent workflows. Many creators will keep using the editor for day-to-day GML.Opera Newsroom

What about GMRT vs the old runtime?

GM-CLI is described as working with both new and existing runtimes. Full GMRT migration is a separate decision from tonight’s terminal smoke.Opera Newsroom

Can I use this in GitHub Actions?

Yes as a pattern—after G1–G6, pin a CLI version, inject secrets safely, and fail on non-zero exits. Validate flags against current --help before you trust a sketch.

Where is official truth?

Opera GMRT announcement, Game Developer Claude/CLI coverage, YoYoGames/gm-cli, and npm @gamemaker/gm-cli.

Related reading

• How to Use Unity CLI - First Agent Safe Editor Session 2026
• How to Use Photon Multiplayer in GameMaker - First Realtime Room Evening 2026
• How to Use Discord Social SDK in GameMaker - First Rich Presence Evening 2026
• How to Make a Rhythm Game in GameMaker - First Music Sync Evening 2026
• Your First GameMaker Steam Demo Export Sanity Check
• GameMaker Studio Guide Hub
• Claude Code Manual Permission Governance

Official and useful sources

• Opera - GameMaker launches GMRT (GM-CLI + Claude Code)
• Game Developer - GameMaker incorporates Claude Code
• YoYoGames/gm-cli
• npm @gamemaker/gm-cli
• GameMaker access keys