Buncha Games Developer CLI

Command-line tools for approved Buncha Games developers who want to manage browser game listings without dashboard file-picker automation.

Use the CLI from your game repo. Do not use direct Cloudflare, R2, Supabase, database, or admin shortcuts.

World provider preparation

Approved first-party and closed-beta World developer tasks can use the six buncha-games worlds commands to prepare a secret-free candidate, deterministic artifact packages, unofficial preflight, a privacy-safe platform handoff, and a token-scoped sanitized status read. These commands provide no platform review, certification, registry-write, migration, deployment, registration, activation, suspension, retirement, or rollback authority.

CLI 0.1.8 is the bounded-upload recovery release, with Provider Kit 0.1.3 pinned exactly. See the dated upload recovery release receipt for publication and Application deployment status. Provider preparation commands and authority are unchanged: publication grants no review, registry, deployment or activation authority. CLI 0.1.7 and Provider Kit 0.1.3 were registry-verified before this release; the old source checkout is not the supported upload distribution.

The Slice 8.2 release adds only options to the same six commands. worlds candidate init --cloud-drafts installs the frozen optional declaration. A provider-owned script runs the Kit adapter, then passes its validated JSON to worlds provider preflight --cloud-draft-evidence <path> and worlds handoff build --cloud-draft-evidence <path>. The CLI never loads or executes provider adapter code and cannot issue official certification.

FL-001C.2 adds worlds candidate init --creator-lifecycle-notifications. A provider returns validated, content-free evidence with --creator-notification-evidence <path> to preflight and handoff commands. Opaque recipient references, account identifiers, assertions, email addresses, child content, and internal moderation notes are forbidden.

Install

npm exec --yes --package @bunchagames/cli -- buncha-games --help

You can also use npx @bunchagames/cli ... in environments where npx is available.

Authenticate

Create a developer API token in the Buncha Games Developer Dashboard, then store it locally as BUNCHA_GAMES_API_TOKEN.

Do not print, echo, log, commit, or paste token values into chat.

$env:BUNCHA_GAMES_API_TOKEN = "paste-token-locally-only"

Common Workflow

# Inspect the current owned-game state.
npm exec --yes --package @bunchagames/cli -- buncha-games games status --site https://bunchagames.com --game-slug my-game --json

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

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

# 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

Large build uploads (UPL-001)

Use CLI 0.1.8 or a subsequent platform-confirmed compatible release. Pin the package in the game repository; do not invoke a stale Platform worktree:

npm install --save-dev --save-exact @bunchagames/[email protected]

The Application requires upload protocol 2 on chunked start, part and completion requests. An outdated client receives HTTP 426 with upload-client-upgrade-required, the minimum CLI version and update command before storage allocation or part acceptance. Authenticated status and cancellation remain available to older clients. The header declares transport support; it is not an authentication or validation bypass.

The existing upload --file, --zip, and --build-dir interface is preserved. Archives of at least 16 MiB use sequential 8 MiB parts, followed by server-side validation of the private stored ZIP. Smaller archives retain the existing path. Total build limits and review/publication requirements do not change.

• Rerun the same command, archive and metadata to resume received parts or recover the existing result after a lost response. Do not change the archive while the command is running.
• --restart-upload discards an incomplete transfer only. It cannot cancel validation, overwrite a created build, or bypass review.
• Transfer sessions last 24 hours. New finalizations have a separate five-minute recovery deadline, measured from their server-recorded start. A subsequent status read or upload retry reconciles the exact build. If none exists, it records a failed-attempt fence before cleaning that attempt's private files and permitting a new upload. A committed build is preserved, not reuploaded. This is request-driven recovery, not a scheduled job. Legacy sessions without a trustworthy finalization start retain their original transfer expiry.
• Processing is not success. The final validated result and Sandbox URL are required; neither grants public promotion.
• Final validation has a separate four-minute response deadline; chunk and control requests retain their two-minute deadline. Keep the CLI running until it returns a result. A timeout is not a validation rejection or permission to start a duplicate build. The CLI reports the recovery deadline while the attempt remains validating. Rerun after that deadline with the same archive and metadata. A cleanup/database outage remains a visible error, never a guessed success or permission to overwrite a validated build.
• There is no fallback that resends a large archive to the old buffered endpoint. A missing/new endpoint error means the CLI and Application rollout must be reconciled, not that the game should be reduced or uploaded directly to R2.

Media Commands

# Upload listing media.
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 exact carousel 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> --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

Images must be JPG, PNG, WebP, or GIF and 8 MB or smaller.

Connected Services And Review

# Confirm low-risk services Buncha Games detected during validation.
npm exec --yes --package @bunchagames/cli -- buncha-games services confirm --site https://bunchagames.com --game-slug my-game --service-ids <service-id-1>,<service-id-2> --json

# Request review for a custom service that cannot be auto-cleared.
npm exec --yes --package @bunchagames/cli -- buncha-games services 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 after the human confirms every 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

Build validation reports connected services in games status --json. Simple games may show no services. Known browser-safe providers may be auto-cleared or require one confirmation. Unknown or risky services still require Buncha Games review, and remote executable scripts remain blocked.

Review submission does not approve or publish a game automatically. It creates a developer-side submission for Buncha Games review.

games status --json Example

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

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.
• Connected services unresolved: confirm expected services, request review, or remove blocked services before review submission.

More Docs

• Developer docs: https://bunchagames.com/developers/docs
• Manual upload path: https://bunchagames.com/developers/docs/upload-without-cli
• CLI guide: https://bunchagames.com/developers/docs/cli
• Agent quickstart: https://bunchagames.com/developers/docs/agent-quickstart