SpriteGuru CLI

CrustJS CLI for humans and agents. Requires Node.js 24 or later. Success output is JSON on stdout; login instructions and errors go to stderr. Errors exit nonzero. Tokens are never printed by the CLI.

Install on macOS

Paste this command into Terminal. It supports Apple Silicon and Intel Macs and needs no sudo or Homebrew:

curl -fsSL https://spriteguru.com/install.sh | bash

Or download the Mac installer, unzip it, and double-click Install SpriteGuru.command. It opens Terminal and runs the same installer.

The installer verifies the package checksum, uses an installed Node.js 24+ when available, or downloads a private Node.js 24 runtime from nodejs.org and verifies its checksum. It installs into ~/.local/share/spriteguru, places a launcher in ~/.local/bin, and adds that directory to your zsh or bash startup file. Open a new terminal afterward or use the full launcher path printed by the installer. Run the installer again to upgrade. It does not change your system Node.js installation or your SpriteGuru sign-in credentials.

For custom locations set SPRITEGURU_INSTALL_DIR and SPRITEGURU_BIN_DIR to absolute paths. SPRITEGURU_SKIP_PATH=1 disables shell-profile editing. Remove the launcher and installation directory to uninstall; credentials are stored separately.

Install from npm

npm install -g @docyrus/spriteguru
spriteguru auth login
spriteguru auth status
spriteguru credits

The npm package requires Node.js 24+. Its default registry is https://registry.npmjs.org/. The package has no runtime npm dependencies; third-party notices are included.

From this repository, npm ci && npm run cli:build builds the CLI and npm run cli -- --help runs it. npm run cli:release prepares the npm tarball and public Mac downloads. npm run cli:publish publishes that reviewed release under the Docyrus organization; publishing requires a logged-in npm account with organization access and any required 2FA. Each release needs a new version in cli/package.json; the CLI version is read from that file. npm run deploy builds release downloads before uploading the site.

The command spriteguru schema returns the Crust command schema, and spriteguru catalog lists supported art styles, actions, asset types, models, video profiles and speech voices. Shell completions: spriteguru completion zsh (also bash and fish).

Create an animation video project

CLI 0.5.2 includes a complete local PixiJS video workspace with 31 visual styles:

spriteguru templates
spriteguru create my-video

create takes only the project folder name. Use a new folder whose parent already exists; the command refuses existing destinations, including empty folders and symlinks. It installs PixiJS, Vite, TypeScript and FFmpeg/FFprobe tools. npm progress goes to stderr and successful results are JSON. If installation fails, the generated files remain; enter the folder and run npm install to resume.

Open the generated folder in Codex or Claude Code, then describe the video you want. It includes:

• A SpriteGuru-branded player with a playable animated demo, resource timeline, captions, seeking, fullscreen, frame downloads and transcript. The timeline shows resource clips, follows playback, and supports selection, zoom and frame-accurate scrubbing.
• Local SpriteGuru and official PixiJS skills in both .agents/skills/ and .claude/skills/, plus AGENTS.md and CLAUDE.md.
• Agent instructions that first ask Explainer, Advertisement or General Video, then offer the available visual styles and the preview gallery, then gather a short creative brief. Each choice is saved before continuing.
• film.config.json, editable TypeScript scenes, localized copy, local asset/production folders, portable HTML5 ZIP export for iframe embedding, and npm run export:mp4 with exact frame capture and output verification.

New projects leave category and template unset in spriteguru.project.json. spriteguru.templates.json lists categories, styles and their installed skills. The 31 visual styles cover cutout, type, vector, technical, character, print, paper, material and cinematic treatments. Every style skill ships with the project, including its relevant visual interview and review criteria. Categories describe purpose and templates describe appearance and motion. The brief establishes audience, tone, message, story, duration and any CTA.

Scaffolding requires no SpriteGuru sign-in and spends no generation credits; dependency installation requires npm access. npm run dev previews the project, and npm run build checks and bundles it. To export, run npm run export:mp4, open its local URL and wait for the verified MP4, or use HTML5 export for embedding. The starter demo is silent; the agent creates narration and music when in scope.

The official PixiJS skills are vendored with their MIT license and a hashed provenance manifest. Skills and template files ship in both the npm package and macOS installer; create does not fetch agent instructions from a remote repository at runtime.

Install the project skill

Run this in the folder where you want your coding agent to use SpriteGuru:

cd /path/to/your/project
spriteguru init

Available in CLI 0.3.0 and later, init writes the bundled skill to .agents/skills/spriteguru/SKILL.md in the current folder. It works offline without signing in and returns JSON containing the absolute path and a created boolean. The skill explains project selection, credit authorization, generation, animation, reference imports, waiting for jobs, and exporting assets.

Running init again refreshes an existing skill with the bundled version without a warning or confirmation (created: false). An identical skill is left unchanged. Skill installation happens when you explicitly run init or scaffold a new project with create. The npm and macOS packages both include the skill.

Authentication and server

The default server is https://spriteguru.com. Use --url http://localhost:5190 on the leaf command or SPRITEGURU_URL to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in ~/.config/spriteguru/credentials.json, with file permissions 0600. Set SPRITEGURU_CONFIG_DIR for an isolated configuration directory. Browser login uses a ten-minute, single-use device code and receives a seven-day revocable Better Auth session. auth login --no-browser prints the URL for manual use. auth logout revokes the token. SPRITEGURU_TOKEN supports secret injection by agent runners; do not put tokens in arguments or commit them.

Agent workflow

spriteguru projects create --name "Forest cast" --style pixel
# Read the returned project.id and use it below.
spriteguru generate PROJECT_ID --name "Knight" --description "A blue knight with a red scarf" --actions idle,walk --yes
spriteguru jobs wait PROJECT_ID JOB_ID --timeout 600
spriteguru jobs list PROJECT_ID
spriteguru projects get PROJECT_ID
spriteguru files list PROJECT_ID
spriteguru files export PROJECT_ID --output forest-cast.zip

jobs wait waits for the specified job only. A drawing may queue follow-up animation jobs; inspect jobs list and wait for those before exporting. Jobs continue on the server if the CLI exits. files export refuses to overwrite a file. projects rename PROJECT_ID --name "New name" and projects delete PROJECT_ID --yes manage the library. models PROJECT_ID --image-model gpt-image-2.5 --video-model heygen/heygen-video-1 sets the defaults for future jobs. The previous --model option remains an alias for --image-model.

Generation and reference imports require --yes, which authorizes credit spending. Read estimates from projects get before submitting. Estimates are ranges; actual provider usage is recorded to your own balance. Paid generation needs configured production provider bindings and secrets.

Image and video model parameters

List valid identifiers with spriteguru catalog. Set models on a single generation:

spriteguru generate PROJECT_ID --name "Knight" --description "A blue knight" \
  --image-model gpt-image-2.5 --video-model heygen/heygen-video-1 \
  --actions idle,walk --yes

generate, jobs submit, and files import accept both --image-model and --video-model. The video selection is used when the job includes an animation. These overrides apply to that job and the animations it explicitly queues; they do not change project defaults. jobs submit flags take precedence over imageModel and videoModel fields in its JSON file. Model identifiers are validated before a job is queued. Jobs return and retain the selected model identifiers, even if project defaults change while they wait.

Set defaults for all future jobs in a project:

spriteguru models PROJECT_ID --image-model gpt-image-2.5 --video-model pruna/p-video-2-pro
# Either selection can be changed independently:
spriteguru models PROJECT_ID --video-model heygen/heygen-video-1
# Or choose them when creating a project:
spriteguru projects create --name "Forest cast" --style pixel \
  --image-model gpt-image-2.5 --video-model heygen/heygen-video-1

An omitted model uses the saved project selection, then the service default. Credit estimates and supported quality settings follow the selected video provider. Reference or redraw operations use the existing GPT Image fallback when the selected image model does not support edits. Configured provider secrets are required for actual generation.

These flags are available in CLI 0.2.0 and later. Rerun the macOS installer to upgrade.

Image, video, music and speech generation

CLI 0.4.0 adds standalone assets alongside the existing sprite commands. Use any project, or create an empty one first. assets list returns saved asset ids, image blob hashes for video references, and the models configured on that server.

spriteguru projects create --name "Adventure assets" --style hd-cartoon
spriteguru assets list PROJECT_ID

spriteguru assets generate PROJECT_ID --type image --name "Forest" \
  --prompt "A moonlit watercolor forest" --model gpt-image-2.5 \
  --aspect-ratio 3:2 --yes

spriteguru assets generate PROJECT_ID --type video --name "Forest breeze" \
  --prompt "Leaves drift slowly in the breeze" --reference IMAGE_BLOB_SHA \
  --model pruna/p-video-2-pro --seconds 5 --resolution 768p --mode quality --yes

spriteguru assets generate PROJECT_ID --type music --name "Adventure theme" \
  --prompt "An instrumental adventure theme with flute and strings" --model lyria-3.5 --yes

spriteguru assets generate PROJECT_ID --type speech --name "Welcome" \
  --prompt "Welcome, traveler. Your next adventure starts here." \
  --model gemini-3.8-flash-lite-tts --voice Kore --delivery "Warm and welcoming" --yes

spriteguru jobs wait PROJECT_ID JOB_ID --timeout 900
spriteguru assets list PROJECT_ID
spriteguru assets download PROJECT_ID ASSET_ID --output welcome.wav
spriteguru files export PROJECT_ID --output adventure-assets.zip

Use the returned job id with jobs wait. For --reference, use an image asset's file SHA from assets list, or a character's art SHA from projects get, from the same project. Video duration, resolution and mode must match its provider's profile in catalog; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when --model is omitted; sprite project model defaults continue to apply to sprite commands.

CLI 0.5.0 adds ElevenLabs speech and SFX:

spriteguru assets generate PROJECT_ID --type speech --model eleven_v4 \
  --name "Narration" --prompt "[whispers] Welcome, traveler." \
  --voice JBFqnCBsd6RMkjVDRZzb --dry-run
spriteguru assets generate PROJECT_ID --type speech --model eleven_v4_turbo \
  --name "Greeting" --prompt "Hello, traveler." --dry-run
spriteguru assets generate PROJECT_ID --type sfx --name "Magic spell" \
  --prompt "A shimmering spell with a soft burst" --seconds 2.5 --loop \
  --prompt-influence 0.6 --dry-run

Replace --dry-run with --yes to generate within your authorized credit budget. ElevenLabs accepts a voice ID in --voice and defaults to George when omitted. Use audio tags in the transcript; --delivery is only for Gemini and is rejected for ElevenLabs. SFX has a single model, eleven_text_to_sound_v2; --seconds accepts 0.5–30 (default 5), --loop requests a seamless loop, and --prompt-influence accepts 0–1 (default 0.3). Both return MP3. catalog includes sfxModels and elevenLabsVoices. The server needs AI_PROVIDER_KEY_ELEVENLABS; provider keys never belong in CLI credentials.

Images have a full background by default; --transparent requests a cutout. Gemini speech's --prompt is the verbatim transcript, and --delivery controls how it sounds without being spoken. Gemini speech supports both gemini-3.8-flash-tts and gemini-3.8-flash-lite-tts. Music uses Lyria. Google audio requires the server's AI_PROVIDER_KEY_GOOGLE secret; no provider keys are stored in the CLI.

Preview a validated request and its estimated credits offline with --dry-run, without signing in or spending credits:

spriteguru assets generate PROJECT_ID --type music --name "Theme" \
  --prompt "A gentle instrumental theme" --dry-run

Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. Omit --dry-run and pass --yes to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:

{"type":"speech","name":"Welcome","prompt":"Welcome, traveler.","model":"gemini-3.8-flash-lite-tts","voice":"Kore","delivery":"Warm and welcoming"}

spriteguru assets submit PROJECT_ID --file speech.json --dry-run
spriteguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-tts --yes

--model overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's assets/<id>/ directory and are shared with the web Assets workspace.

Typed job files

Use spriteguru jobs submit PROJECT_ID --file job.json --yes. The server and CLI validate the same schema. Available job bodies:

{"kind":"character","name":"Knight","description":"A blue knight with a red scarf","style":"pixel","subjectKind":"character","actions":["idle","walk"]}

{"kind":"animate","character":"knight-SLUG","actions":["run","jump"]}

{"kind":"redraw","character":"knight-SLUG","change":"Give the knight a green helmet"}

For named motions, especially video and collage subjects:

{"kind":"custom","character":"knight-SLUG","name":"Wave hello","prompt":"The character raises one arm, waves twice and lowers it back to its starting pose, staying in place.","frames":["Arm resting by the side","Arm raised with open hand","Hand waving to the right","Arm resting by the side"],"loop":false,"returns":true,"fps":12}

Custom motions require 2–12 frame descriptions, a 20–600 character prompt, and 4–24 fps. Character identifiers are returned by projects get. Built-in actions must match the subject kind.

Reference images:

spriteguru files import PROJECT_ID --file knight.png --name Knight --description "Keep the blue armor" --yes

PNG, JPEG and WebP are accepted up to 10 MB. A configured service redraws the reference and charges credits; otherwise it imports the original artwork.

Expanded video workflows and studies

New workspaces offer Explainer, Advertisement and General Video independently of visual style. Eight advertising and five general-video workflows are installed as focused references. Existing advertorial project choices remain compatible; completed briefs and style IDs are reused.

Twenty original procedural 2.5D studies are bundled. In an untouched project, npm run example -- risograph-print installs a runnable study, with starter backups and refusal to replace an authored film. npm run review prints a local browser URL and saves text-bound checks, deterministic seek comparisons and frames to production/review/. Review moving playback and audio too. Physically rendered 3D is deferred.