game-asset-cli

Stateless CLI for generating and post-processing game assets.

The tool does not create projects, keep job state, start a daemon, or write hidden state. Every command reads explicit inputs and writes explicit outputs.

Build

cargo build

The binary name is game-asset.

Implemented Commands

Image and sprite utilities:

game-asset image generate --kind scene --prompt prompt.md --ref key.png --out scene.png
game-asset image green-source --kind button --prompt prompt.md --ref crop.png --out button_green.png
game-asset image crop --in scene.png --box 120,80,240,96 --out crop.png
game-asset image chroma-key --in button_green.png --out button.png --trim
game-asset sprite normalize --in hero.png --size 512x512 --out hero_norm.png
game-asset sprite sheet-slice --in hero_sheet.png --grid 8x1 --out-dir frames
game-asset sprite sheet-pack --in-dir frames --cols 8 --out hero_sheet.png --metadata-out hero_sheet.json

Audio utilities:

game-asset audio bgm --prompt bgm.md --instrumental --out bgm.mp3
game-asset audio sfx --preset coin --duration-ms 260 --out coin.wav
game-asset audio waveform --in coin.wav --out coin_waveform.png
game-asset audio trim --in raw.wav --start 0.1 --end 1.8 --out trimmed.wav

audio trim and audio waveform accept PCM WAV input (8/16/24/32-bit integer or 32-bit float); trim preserves the input sample format. Compressed inputs such as mp3 are not decoded and fail with a clear error — convert to WAV first.

With --json, every command emits a leading start event and a trailing done event; failures emit a single {"type":"error",...} event to stdout. Add --json-include-prompts to include prompt text in provider_request events.

Audit and metadata:

game-asset contact-sheet --in "assets/*.png" --out contact.png
game-asset manifest --in dist/assets --out assets.manifest.json
game-asset doctor

Video slicing:

game-asset video slice --in effect.mp4 --start 0.4 --end 1.6 --frames 12 --out-dir fx/hit

video slice requires ffmpeg on PATH.

Self-update:

game-asset upgrade --check           # report whether a newer release exists
game-asset upgrade                   # download and install the latest release
game-asset upgrade --tag v0.2.0      # install a specific tag
game-asset upgrade --dry-run         # resolve the platform asset without installing
game-asset upgrade --force           # reinstall even if already current

upgrade downloads the release archive for the current platform from GitHub, verifies it contains the game-asset binary, and atomically replaces the running executable in place (no cargo toolchain required). Set GITHUB_TOKEN (or GH_TOKEN) for private repositories or to raise the API rate limit, and --repo owner/name to install from a fork. It requires tar on PATH and write access to the directory holding the binary.

Providers

Image generation wraps the local Codex CLI:

• CODEX_BIN optionally points to the Codex executable.
• CODEX_SANDBOX defaults to workspace-write.
• --timeout-seconds controls the Codex subprocess timeout for image commands.
• doctor checks the Codex binary and codex exec availability, but does not run a model/image generation probe by default.

Background music uses the MiniMax music API:

• MINIMAX_API_KEY must be set for audio bgm.

Short SFX are generated locally and deterministically.

Docs

See docs/ for the product spec, technical design, provider design, and roadmap.