vg media: fal.ai endpoint runner

vg media is the agent-first CLI for fal.ai. It works in a terminal for humans (pretty output) and equally well for agents (structured JSON when piped or with --json). All other skills in this repo call vg media for execution; they do not wrap the fal.ai HTTP API directly. The surface mirrors the upstream genmedia CLI — that's where the skill name comes from — but the implementation is vibedgames' own: every call is forwarded through a single server proc that attaches the FAL key and proxies to fal.

Vibedgames runtime. Install with npm install -g vibedgames (or pnpm dogfood in this repo). The vibedgames server holds the FAL_KEY, so there is no per-machine setup. The CLI exposes run, status, models, schema, upload, pricing, and docs — the read/write surface that maps to fal's queue, platform, storage, and docs APIs.

For the full command surface (every flag, every option, every example), see references/full-reference.md. For setup details, see the Setup section below.

Critical rules

1. Always use --json when an agent will read the output. Pretty mode is for humans only.
2. Never invent endpoint IDs. Use vg media models "<query>" to discover, vg media models --endpoint_id <id> to verify.
3. Inspect schema before running. vg media schema <endpoint_id> --json shows the exact field names. Guessed flags fail with 422.
4. Save files with --download, not curl. The CLI handles authentication, naming, and file format detection.
5. Use --async for long-running generation. Image work usually completes inline; video/audio/3D usually need queue + status polling.

Command index