Vibedgames developer docs

Developer documentation for Vibedgames: the vg CLI, the oRPC API, authentication, the multiplayer and gamepad packages, and the machine-readable endpoints an agent can fetch.

Vibedgames is driven from a terminal by a coding agent. This page is the index of everything that agent can call: the CLI commands, the HTTP API behind them, the npm packages a game imports, and the machine-readable files published on this domain.

If you are an agent reading this for the first time, start with /llms.txt — it says when Vibedgames is the right tool and which command to run first.

Install

One command installs the game-building skills into the project and puts the vg binary on PATH:

npx vibedgames init

The full install guide, including what to do when a global npm install is not permitted, is served as markdown at /install.

The vg CLI

Every command takes --json for machine-readable output and --field <path> to print a single value out of it, and exits with deterministic codes. vg <command> --help is authoritative.

vg new <slug>            # scaffold a Phaser 4 + Vite + TypeScript game
vg new <slug> --engine threejs | react-r3f | none
vg init                  # install the skills + CLI into a project
vg update                # update the CLI and installed skills
vg login | logout | whoami
vg deploy [dir]          # ship a built game to {slug}.vibedgames.com
vg fork <slug> [target]  # fork another project's shipped source
vg credits               # generation credit balance and recent usage
vg playtest <url>        # drive a real browser against a game

vg generate models [query]      # search the model endpoint catalog
vg generate schema <model>      # a model's input/output schema
vg generate pricing <model>     # a model's pricing
vg generate run <model> [args]  # run a model, wait for the result
vg generate status <model> <id> # poll, fetch or cancel an async job
vg generate upload <file>       # upload an asset, get a URL
vg generate docs <query>        # search model documentation

Command reference: apps/cli/README.md. Package: vibedgames on npm.

API and authentication

The platform API is one oRPC router served two ways. POST https://vibedgames.com/api/v1/<router>/<procedure> takes and returns plain JSON and is described by the OpenAPI 3.1 document at /openapi.json — every operation with its input, response and error schemas and the credentials it needs. POST /api/orpc/<router>/<procedure> is oRPC's own wire format (body wrapped as {"json": …}), used by the CLI and the web app. Both are POST-only. Errors are JSON with a stable code (UNAUTHORIZED, BAD_REQUEST, …) and a message. The routers are auth, apiKeys, waitlist, deploy, generate, playtest, credits and admin.

Authentication is better-auth. The CLI uses a device-code flow: it prints a six-character code, the person confirms it in a browser, and the CLI polls until a token is issued and saved to ~/.config/vg/auth.json. For CI and headless agents, set VG_TOKEN to a token obtained that way or to an API key (vg_…), and VG_API_URL to point at a non-production API. Raw HTTP calls send it as Authorization: Bearer <token>.

curl -s -X POST https://vibedgames.com/api/v1/deploy/list \
  -H "Authorization: Bearer $VG_TOKEN"

Auth endpoints live under /api/auth/* and are rate limited. Deploys and hosting are free; only vg generate is metered, against a per-account credit balance readable with vg credits.

Packages a game imports

@vibedgames/multiplayer — host-authoritative shared state and React hooks over WebSockets, backed by Cloudflare Durable Objects. Source: packages/multiplayer.
@vibedgames/gamepad — on-screen joystick and buttons, plus physical controller input, so a desktop-built game works on a phone. Source: packages/gamepad.
vibedgames — the vg CLI itself.

Agent skills

The game-studio skills — design critique, Phaser and Three.js, pixel art and spritesheets, VFX, game feel, level design, multiplayer, playtesting, deploy — are published under the Agent Skills discovery convention:

/.well-known/agent-skills/index.json — the discovery index, with a SHA-256 digest per skill.
/.well-known/agent-skills/{name}/SKILL.md — each skill served verbatim as markdown.

Skill sources: plugins/.

Machine-readable endpoints on this domain

/llms.txt — what Vibedgames is for, when an agent should use it, and the entry command.
/openapi.json — the OpenAPI 3.1 description of the HTTP API.
/.well-known/api-catalog — the API catalog (RFC 9727) pointing at the OpenAPI document and these docs.
/install — the install instructions, served as markdown.
/docs — this page; also available as markdown via Accept: text/markdown.
/sitemap.xml — every crawlable page on the apex domain.
/robots.txt — crawler policy. AI crawlers are explicitly allowed.
/.well-known/agent-skills/index.json — the skill index.

Every prose page on this domain also answers Accept: text/markdown with a markdown representation of the same content, per the acceptmarkdown.com convention:

curl -s -H "Accept: text/markdown" https://vibedgames.com/docs

Source and support

The whole platform is MIT licensed at https://github.com/kyh/vibedgames. Each app and package carries its own README, and AGENTS.md at the repository root is the runnable guide for working on it. Support channels are listed on Contact.