aispritemaker CLI

aispritemaker is a command-line tool for the REST API. One command creates a job, waits for it, and writes the sheet into your project, with frame data your engine can read. It’s handy in build scripts, for batch-generating a cast of characters, and for converting sheets you already have into Godot SpriteFrames. Node 18 or newer, no dependencies.

Quick start

npx aispritemaker login
npx aispritemaker generate "a knight with a blue cape" --motion walk --directions 4 --size 64 --out ./sprites

That writes a-knight-with-a-blue-cape_walk.png and .json to ./sprites. A 4-direction walk costs 4 × 10 credits.

To keep it installed instead of using npx:

npm install -g aispritemaker

Authentication

Every plan includes API access. Create a key at Dashboard → API keys. The CLI looks for a key in this order:

1. --api-key asm_live_... on the command line;
2. the ASM_API_KEY environment variable;
3. ~/.config/aispritemaker/config.json, written by login with file mode 0600 ($XDG_CONFIG_HOME is respected).

npx aispritemaker login                          # paste the key (hidden); it's checked against /api/v1/me
echo "$ASM_API_KEY" | npx aispritemaker login    # non-interactive, e.g. in CI
npx aispritemaker logout

Commands

Every command accepts --json (machine-readable output on stdout and nothing else), --quiet, --api-key and --base-url.

generate

# still sprite, 4 variations
npx aispritemaker generate "health potion, round flask, red liquid" --size 32 --style 8-bit --count 4

# library animation in 4 directions, plus a Godot .tres
npx aispritemaker generate "fox knight" --motion walk --directions 4 --view topdown --format png,json,godot --out ./game/sprites

# reuse a character from an earlier job, or start from a reference image
npx aispritemaker generate "fox knight" --motion attack-slash --character as_01JC...
npx aispritemaker generate "same character, holding a torch" --reference ./hero.png

# 8-direction turnaround and a tileset
npx aispritemaker generate "wizard in purple robes" --type directions --directions 8
npx aispritemaker generate "mossy dungeon floor" --type tileset --size 32

Files it writes

For generate "fox knight" --motion walk:

• fox-knight_walk.png: the sheet. One row per direction, one column per frame, transparent background.
• fox-knight_walk.json: Aseprite-compatible JSON: frames[] with rectangles and duration, meta.frameTags with one tag per animation (walk_down, walk_left, …), and meta.aispritemaker with the job id, fps, frame size and directions. Phaser loads it with this.load.aseprite, Aseprite reads it, and our Godot addon and Unity package convert it.
• fox-knight_walk.tres (with --format godot): a Godot 4 SpriteFrames. If --out is inside a Godot project (there’s a project.godot above it), the texture path is the correct res:// path.

If you press Ctrl+C while waiting, the job keeps running on our side. Resume with aispritemaker wait <id>.

convert

Convert sheets you already have, with no API key and no credits:

npx aispritemaker convert sprites/hero.json --to godot                 # PNG + JSON -> hero.tres
npx aispritemaker convert sprites/coin.png --frame-size 16 --fps 8     # plain PNG grid -> coin.tres
npx aispritemaker convert sheet.json --to json                         # normalize any sheet JSON

It reads our exports, Aseprite JSON (array or hash; frame tags with forward, reverse and pingpong) and TexturePacker JSON (hash or array, with an animations map).

mcp

Prints ready-to-paste MCP config for Claude Code, Cursor, Codex, VS Code and stdio-only clients:

npx aispritemaker mcp --client claude
# claude mcp add --transport http aispritemaker https://aispritemaker.com/mcp --header "Authorization: Bearer $ASM_API_KEY"

Full setup per client is in the MCP docs.

Scripting and CI

With --json, output is a single JSON document on stdout, and errors print { "error": { "code", "message" } }. Exit codes:

Example: regenerate a set of enemies in a build step and fail the build if anything goes wrong:

set -e
for enemy in "green slime" "skeleton warrior" "cave bat"; do
  npx aispritemaker generate "$enemy" --motion idle --size 32 --format png,json,godot --out ./game/enemies --json > /dev/null
done

The package can also be used as a library:

import { Client } from "aispritemaker";

const api = new Client({ baseUrl: "https://aispritemaker.com", apiKey: process.env.ASM_API_KEY });
const { id } = await api.createJob({ type: "animation", prompt: "slime", motion_id: "idle" });
const job = await api.waitForJob(id);

Using the helper script today

Until the npm release, the helper in the Claude Code plugin zip gives you the same generate-and-save flow. Unzip it, then:

export ASM_API_KEY="asm_live_…"
H=aispritemaker/skills/aispritemaker/scripts/asm.mjs

node $H motions
node $H balance
node $H generate --prompt "green slime" --type animation --motion idle --size 32 --directions 1 --out ./sprites --name slime
node $H job <id>
node $H wait <id> --out ./sprites --name slime

It prints JSON and writes <name>.png plus <name>.json (Aseprite-style frames and one tag per direction), the same files generate writes by default. It doesn’t do convert or Godot .tres output; the Godot addon converts the JSON for you.