Buncha Games Developer CLI

What the CLI is for

The Buncha Games Developer CLI is the supported command-line path for agent-friendly game publishing work. Use it from your game repo when a developer API token is available.

The CLI uses Buncha Games developer APIs. It should replace fragile dashboard scraping, browser file-picker automation, and direct Cloudflare, R2, Supabase, or admin shortcuts.

Create and update draft game listings.
Upload exported browser game ZIP builds.
Upload, reorder, move, and remove listing media.
Check owned-game status as stable JSON.
Request external-domain review.
Submit a validated game for Buncha Games review after the human confirms required attestations.

Install and authenticate

Use npm exec or npx to run the published package. The npm package page is https://www.npmjs.com/package/@bunchagames/cli.

Store your developer API token locally as BUNCHA_GAMES_API_TOKEN and never paste, print, or commit it.

During Alpha, developer tokens are created in the private Developer Dashboard. The CLI should fail clearly when the token is missing or invalid.

# PowerShell example. Do not print the token value.
$env:BUNCHA_GAMES_API_TOKEN = "paste-token-locally-only"

npm exec --yes --package @bunchagames/cli -- buncha-games --help
npm exec --yes --package @bunchagames/cli -- buncha-games games status --site https://bunchagames.com --game-slug my-game --json

End-to-end listing workflow

# 1. Create a draft listing from a manifest.
npm exec --yes --package @bunchagames/cli -- buncha-games games create --site https://bunchagames.com --manifest ./buncha-game-manifest.json --json

# 2. Update listing metadata later from the same manifest shape.
npm exec --yes --package @bunchagames/cli -- buncha-games games update --site https://bunchagames.com --game-slug my-game --manifest ./buncha-game-manifest.json --json

# 3. Upload an exported browser build ZIP.
npm exec --yes --package @bunchagames/cli -- buncha-games upload --site https://bunchagames.com --game-slug my-game --file ./dist/my-game.zip --json

# 4. Check the current game, checklist, build, media, review, and next-step state.
npm exec --yes --package @bunchagames/cli -- buncha-games games status --site https://bunchagames.com --game-slug my-game --json

Media upload and carousel management

Use media commands after the game record exists. Images must follow the same dashboard rules: JPG, PNG, WebP, or GIF, 8 MB or smaller, with useful alt text.

Screenshots appear in carousel order. Upload screenshots in the desired order, or use reorder when an agent needs an exact final order. The public carousel uses up to five total media assets.

# Upload thumbnail, hero, and screenshots.
npm exec --yes --package @bunchagames/cli -- buncha-games media upload --site https://bunchagames.com --game-slug my-game --type thumbnail --file ./media/thumbnail.webp --alt "Thumbnail showing the game title" --json
npm exec --yes --package @bunchagames/cli -- buncha-games media upload --site https://bunchagames.com --game-slug my-game --type hero --file ./media/hero.webp --alt "Hero image showing the main play area" --json
npm exec --yes --package @bunchagames/cli -- buncha-games media upload --site https://bunchagames.com --game-slug my-game --type screenshot --file ./media/screenshots/01.webp --alt "Gameplay screenshot of the first area" --json

# Move one media item by one slot.
npm exec --yes --package @bunchagames/cli -- buncha-games media move --site https://bunchagames.com --game-slug my-game --media-id <media-id> --direction up --json

# Set the exact media order.
npm exec --yes --package @bunchagames/cli -- buncha-games media reorder --site https://bunchagames.com --game-slug my-game --media-ids <id-1>,<id-2>,<id-3>,<id-4>,<id-5> --json

# Remove one media item.
npm exec --yes --package @bunchagames/cli -- buncha-games media remove --site https://bunchagames.com --game-slug my-game --media-id <media-id> --json

External domains and review submission

External domains are reviewed before public play. Domain requests do not approve anything automatically.

Review submission also does not approve anything automatically. It creates a developer-side submission for Buncha Games review and requires explicit human attestations.

# Request review for a required browser-visible service.
npm exec --yes --package @bunchagames/cli -- buncha-games domains request --site https://bunchagames.com --game-slug my-game --domain api.example.com --service-type other --service-name "Example API" --purpose "Loads public browser game data." --json

# Submit only after the human confirms each attestation.
npm exec --yes --package @bunchagames/cli -- buncha-games review submit --site https://bunchagames.com --game-slug my-game --content-disclosure "No adult content, gambling, crypto, or sensitive content." --rights-confirmed --content-policy-confirmed --external-services-confirmed --terms-accepted --json

Manifest shape

Use a JSON manifest for listing create and update commands so agents do not fight shell quoting. Keep descriptions concise and player-facing.

{
  "title": "My Browser Game",
  "slug": "my-browser-game",
  "shortDescription": "A one-sentence player-facing summary.",
  "longDescription": "A short paragraph about what players do.",
  "contentCeiling": "everyone",
  "categories": ["arcade"],
  "platforms": ["desktop"],
  "modes": ["single_player"],
  "controls": ["keyboard", "mouse"],
  "orientation": "landscape",
  "mobileReady": false,
  "minPlayers": 1,
  "maxPlayers": 1
}

Status JSON example

Use games status --json after each major step. Agents should parse this JSON instead of scraping dashboard pages.

{
  "ok": true,
  "gameId": "00000000-0000-0000-0000-000000000000",
  "gameSlug": "my-game",
  "status": "sandbox_validated",
  "checklist": {
    "build": "validated",
    "media": "complete",
    "domains": "clear",
    "review": "ready"
  },
  "media": {
    "thumbnail": 1,
    "hero": 1,
    "screenshots": 3
  },
  "next": [
    {
      "label": "Open Sandbox",
      "href": "https://bunchagames.com/dev/games/<id>/sandbox"
    },
    {
      "label": "Submit for Review",
      "href": "https://bunchagames.com/dev/games/<id>/publish"
    }
  ]
}

Safety rules for agents

Run CLI commands from the game repo or a neutral working folder, not by editing the Buncha Games platform repo.
Use BUNCHA_GAMES_API_TOKEN only from the local environment. Never print token values.
Do not upload source projects, .env files, node_modules, server code, or private keys.
Do not use direct Cloudflare, R2, Supabase, or admin shortcuts.
Do not submit for review unless the human explicitly confirms the required rights, content, external-service, and terms attestations.

Common errors

Missing token: set BUNCHA_GAMES_API_TOKEN locally and rerun the command without printing the token.
Forbidden or not found: confirm the token belongs to the developer account that owns the game.
Validation failed: rebuild a clean exported browser build and make sure index.html is at the ZIP root.
Only Sandbox-validated games can be submitted: upload and validate a build before review submit.
External domains unresolved: request or remove required domains before review submission.

All docs Request invite