AnimaGuru 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://animaguru.com/install.sh | bash

Or download the Mac installer, unzip it, and double-click Install AnimaGuru.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/animaguru, 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 AnimaGuru sign-in credentials.

For custom locations set ANIMAGURU_INSTALL_DIR and ANIMAGURU_BIN_DIR to absolute paths. ANIMAGURU_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/animaguru
animaguru auth login
animaguru auth status
animaguru 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 animaguru schema returns the Crust command schema, and animaguru catalog lists supported art styles, actions, asset types, models, video profiles and speech voices; catalog --type music (or sprites, image, video, speech, sfx, avatars) returns only that part. Shell completions: animaguru completion zsh (also bash and fish).

Required updates

Starting with CLI 0.16.2, commands check https://animaguru.com/cli/release.json before doing work. When a newer stable release is available, the command exits nonzero before running and prints a JSON cli_update_required error to stderr, including the installed/latest versions and update instructions. This applies to humans and agents, including local scaffolding and dry runs. Run the same macOS installer again, or use the npm command in the error for an npm installation, verify animaguru --version, and retry the original command.

animaguru update checks the current release and prints JSON with update instructions; it does not install anything. Help, --version, schema, shell completion, and auth logout remain available while outdated. The check has a three-second timeout and sends no account credentials. If it fails, the last known release in ~/.config/animaguru/cli-release.json (or ANIMAGURU_CONFIG_DIR) still enforces a known update. With no known newer version, offline work continues with a warning. A successful check on the next invocation refreshes the saved release.

CLI versions before 0.16.2 need one manual update to gain enforcement. Publish the npm release before deploying the matching site release so the required version is available through both installation methods.

Create an animation video project

CLI 0.16.2 also installs animaguru-art-motion for Codex and Claude Code: one skill with 36 English art-treatment references and nine explainer motion grammars, plus AnimaGuru generation, timing, camera and review guidance. Request it explicitly for a custom film treatment; its references are separate from the gallery presets. Source coverage and the upstream MIT notice are included in the skill.

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

animaguru templates
animaguru 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:

• An AnimaGuru-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 AnimaGuru 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 animaguru.project.json. animaguru.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 AnimaGuru 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.

CLI 0.16.1 also installs AnimaGuru Cutcraft in both agent skill folders. Ask your agent to use $animaguru-cutcraft for tactile paper-collage explainers with exact editorial lettering, one narrator and purposeful cutout motion. Its generation adapter checks the server's enabled models, tracks asynchronous jobs and supports controlled animation of generated transparent artwork when precise placement is needed or video providers are unavailable. Cutcraft is an additional skill; the gallery retains its 31 visual styles.

Install the project skill

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

cd /path/to/your/project
animaguru init

Available in CLI 0.3.0 and later, init writes the bundled skill to .agents/skills/animaguru/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://animaguru.com. Use --url http://localhost:5190 on the leaf command or ANIMAGURU_URL to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in ~/.config/animaguru/credentials.json, with file permissions 0600. Set ANIMAGURU_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. ANIMAGURU_TOKEN supports secret injection by agent runners; do not put tokens in arguments or commit them.

Personal and team projects

CLI 0.7.1 can select a cloud workspace for project listing, project creation, and credit balances:

animaguru workspaces list
animaguru workspaces use team_0123456789abcdef0123456789abcdef
animaguru projects list
animaguru projects create --name "Shared cast"
animaguru credits
animaguru workspaces use personal

Use a team ID returned by workspaces list. The choice is saved per server in the existing credentials file. workspaces list also shows invitations; accept invitations in the web app before selecting that team. projects get, generation, jobs, and files use the project ID and work for any project you can access, regardless of the selected workspace. With ANIMAGURU_TOKEN, set ANIMAGURU_WORKSPACE=personal or a team ID instead of saving a selection. A cloud team is separate from the local animaguru create workspace NAME video folder.

Agent workflow

Remote projects have no art style. projects create takes a name only. Choose the style for each sprite with generate --style or files import --style (hd-cartoon when left out); local film setup keeps its separate style interview.

animaguru projects create --name "Forest cast"
# Read the returned project.id and use it below.
animaguru generate PROJECT_ID --name "Knight" --description "A blue knight with a red scarf" --style pixel --actions idle,walk --yes
animaguru jobs wait PROJECT_ID JOB_ID --timeout 600
animaguru jobs list PROJECT_ID
animaguru projects get PROJECT_ID
animaguru files list PROJECT_ID
animaguru 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. projects move PROJECT_ID --to OTHER_PROJECT_ID --characters SLUG,SLUG --assets ASSET_ID --avatars GROUP_ID moves characters (with all their animations), saved assets and the project's own avatars to another project you can write to, without regenerating anything (CLI 0.16.0). 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 animaguru catalog. Set models on a single generation:

animaguru 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:

animaguru models PROJECT_ID --image-model gpt-image-2.5 --video-model pruna/p-video-2-pro
# Either selection can be changed independently:
animaguru models PROJECT_ID --video-model heygen/heygen-video-1
# Or choose them when creating a project:
animaguru projects create --name "Forest cast" \
  --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.

animaguru projects create --name "Adventure assets"
animaguru assets list PROJECT_ID

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

animaguru 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

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

animaguru 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

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

Use the returned job id with jobs wait, or add --wait to wait in the same command and --download PATH to also save the result (see below). 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:

animaguru assets generate PROJECT_ID --type speech --model eleven_v4 \
  --name "Narration" --prompt "[whispers] Welcome, traveler." \
  --voice JBFqnCBsd6RMkjVDRZzb --dry-run
animaguru assets generate PROJECT_ID --type speech --model eleven_v4_turbo \
  --name "Greeting" --prompt "Hello, traveler." --dry-run
animaguru 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.

CLI 0.8.0 adds MiniMax H3 Max Turbo and the H3 workflows. MiniMax H3 Max and H3 Max Turbo on fal.ai (fal/minimax-h3-max, fal/minimax-h3-max-turbo) also write videos from text and extend saved videos. Choose with --workflow:

# End on a pose, pin saved audio as the soundtrack, and keep a repeatable seed.
animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max-turbo \
  --name "Hero lands" --prompt "The hero leaps and lands in a crouch" \
  --reference START_IMAGE_SHA --end-reference END_IMAGE_SHA --soundtrack AUDIO_SHA \
  --prompt-expansion balanced --seed 42 --resolution 1080p --dry-run
# Write a scene from text alone.
animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
  --workflow text-to-video --name "Harbor" --prompt "A foggy harbor at dawn" \
  --aspect-ratio 21:9 --seconds 8 --resolution 768p --dry-run
# Add six seconds to a saved video at 2K, guided by saved audio.
animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
  --workflow extend-video --source VIDEO_SHA --name "Harbor, continued" \
  --prompt "Audio 1 for the gulls. The fog lifts and a ship sails out" \
  --audio-references AUDIO_SHA --seconds 6 --resolution 2k --dry-run

--end-reference can be used without --reference; the video then ends on that image. --soundtrack takes a music, speech or SFX asset's file SHA and replaces the generated sound; the video must be at least 2 seconds. Text-to-video takes --aspect-ratio 21:9, 16:9 (default), 4:3, 1:1, 3:4 or 9:16. Extensions take a video asset's SHA as --source (1.6–60 seconds, up to 50 MB), bill --seconds of new footage, offer 2K, and keep the source's shape unless --aspect-ratio crops it. --extend-output continuation returns only a 1.625-second overlap and the new footage. Extensions take up to three comma-separated --audio-references (2–15 seconds each, 15 seconds in total); refer to them in the prompt as Audio 1, Audio 2 and so on. --prompt-expansion is disabled (default), balanced or quality; for extensions, any value other than disabled turns expansion on. Each model's videoProfiles entry in catalog lists its workflows, resolutions and options. The server needs AI_PROVIDER_KEY_FAL.

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:

animaguru 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"}

animaguru assets submit PROJECT_ID --file speech.json --dry-run
animaguru 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, and the error lists the flags that type accepts.

assets generate and assets submit accept --wait to block until the job finishes (failing if generation fails) and --download PATH to wait and then save the result; --timeout sets the wait in seconds (default 600). A PATH that is an existing folder or ends in / receives NAME.EXT, named after the asset and its type (.wav, .mp3, .png…). The JSON output adds job, asset (id, name, type, mimeType) and download (path, size) to the submission receipt.

animaguru assets generate PROJECT_ID --type speech --name vo-01-hook \
  --prompt "Four channel reports." --voice Kore --download production/audio/vo/ --yes

assets batch submits several requests from one file. The file is a JSON list of asset requests, or {"defaults": {...}, "assets": [...]} with the defaults merged under each item, so voiceover lines can share their type, model, voice and delivery:

{"defaults":{"type":"speech","model":"gemini-3.8-flash-tts","voice":"Kore","delivery":"Confident keynote announcer"},
 "assets":[{"name":"vo-01-hook","prompt":"Four channel reports."},{"name":"vo-02-problem","prompt":"Your data lives apart."}]}

animaguru assets batch PROJECT_ID --file vo-lines.json --dry-run
animaguru assets batch PROJECT_ID --file vo-lines.json --download production/audio/vo --yes

Every item is validated before anything is sent, names must be distinct, and a batch holds up to 50 items. --dry-run returns each item's estimate and the total. Items are submitted one at a time; if a submission fails, the batch stops and prints items (already queued, with their job ids), notSubmitted and error, so nothing is resubmitted blindly. With --wait or --download, every job is waited on under one --timeout, and each result is saved into the folder as NAME.EXT. The output is { "items": [{ "name", "id", "estimatedCredits", "job", "asset", "download" }], "estimatedCredits" }; an item that failed or timed out carries its own error, and the command exits non-zero after printing the list. 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.

HeyGen avatars

CLI 0.13.0 adds avatars for HeyGen's avatar API. A group is a character; its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. Any project can browse HeyGen's public catalog. An avatar you create belongs to the project that created it: only that project lists, changes or deletes it.

animaguru avatars list PROJECT_ID --limit 10
animaguru avatars looks PROJECT_ID --avatar-type studio_avatar
animaguru avatars list PROJECT_ID --ownership private

# A synthetic character from a description.
animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
  --prompt "Woman in her early 30s, warm smile, navy blazer, bright studio, soft key light" \
  --aspect-ratio 16:9 --dry-run
# A new outfit or setting for one of the project's avatars.
animaguru avatars create PROJECT_ID --type prompt --name "Ada, keynote" \
  --look LOOK_ID --prompt "On a conference stage under a spotlight" --yes
# A photo avatar from a saved image, an HTTPS URL or a local file.
animaguru avatars create PROJECT_ID --type photo --name "Sam" \
  --file portrait.jpg --subject-consent --yes
animaguru avatars wait PROJECT_ID LOOK_ID

create and add-looks return the new look IDs. Looks start processing; avatars wait polls until HeyGen finishes (completed) or fails. --file and --reference-images take a project image's SHA (from assets list, or a character's art), an HTTPS URL HeyGen downloads (up to 32 MB), or a local file sent inline (up to 8 MB). Photos and footage show a real person: pass --subject-consent only when that person agreed to become an avatar.

A digital twin trains on footage of a real person (about two minutes of natural talking: a project video SHA, a URL or a local file) and clones their voice. It renders only after that person records consent on camera:

animaguru avatars create PROJECT_ID --type digital_twin --name "Sam" \
  --file https://example.com/sam-footage.mp4 --subject-consent --yes
animaguru avatars consent PROJECT_ID GROUP_ID      # a 24-hour link for that person
animaguru avatars get PROJECT_ID --group GROUP_ID  # consentStatus: pending, accepted or rejected

Look Packs dress one of the project's looks in a themed set of five looks; a single template makes two. avatars templates lists their IDs, each in a female and a male variant:

animaguru avatars templates
animaguru avatars add-looks PROJECT_ID --look LOOK_ID \
  --template 5a8e6be843ee4321a014946bf62aa322 --aspect-ratio 9:16 --yes

Credits are charged once HeyGen accepts a request: 132 for a photo or prompt avatar, 213 for a digital twin, and 132 for each generated look (a Look Pack makes five). --dry-run validates and estimates offline; the server checks files, avatar ownership and credits before calling HeyGen. Paid requests carry a retry key, so a retried request is not charged twice. avatars rename PROJECT_ID LOOK_ID --name NAME and avatars voice PROJECT_ID GROUP_ID --voice VOICE_ID change the project's own avatars. avatars delete PROJECT_ID --group GROUP_ID --yes (or --look LOOK_ID) deletes for good; deleting an avatar's last look deletes the avatar. The server needs AI_PROVIDER_KEY_HEYGEN.

Typed job files

Use animaguru 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:

animaguru files import PROJECT_ID --file knight.png --name Knight --style pixel --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.

Motion library

CLI 0.14.0 adds animaguru motion. Search ready-made motion design examples (PixiJS scenes built on the video film kit) by describing the motion, then install one into a film. Search uses natural language and keywords together; it needs animaguru auth login and spends no credits.

animaguru motion categories
animaguru motion search word slam on a beat --category kinetic-typography
animaguru motion search swipe to delete list --labels mobile --limit 3
animaguru motion get skeleton-list-swipe                      # beats, options, usage and code
animaguru motion get skeleton-list-swipe --write src/scenes   # writes the scene and its lib/ modules
animaguru motion get skeleton-list-swipe --write animations/launch/src/scenes   # workspace: imports runtime/kit

Then call the entry function from Film.build(), for example skeletonListSwipe(this, { at: 4 }). --write refuses to replace an existing scene (pass --force) and keeps shared modules that already exist.

Asset library

CLI 0.15.0 adds animaguru library. Pro and Team accounts (and members of a team on the Team plan) can search AnimaGuru's asset library: ready-made sprites with animation sheets, images, video clips, music, voice-over speech and sound effects. Search uses natural language and keywords together. Importing into a project or downloading spends no credits, so check the library before generating a common asset.

animaguru library types                                   # types, counts, and whether this account has access
animaguru library search whoosh for a scene transition --type sfx
animaguru library search upbeat piano background --labels corporate --limit 3
animaguru library get pixel-knight                        # description, details (length, size, frames) and files
animaguru library import pixel-knight --project PROJECT_ID  # sprites become characters, media become saved assets
animaguru library download mountain-lake-sunrise --output assets/   # saves ID.EXT; sprites save ID/ with sheets and animation.json

An imported image, clip or audio file appears in assets list with its file SHA, so it can start an image-to-video generation or be a soundtrack. A sprite's animation.json lists frame rectangles [x, y, w, h], per-frame durations, fps, loop and pivot. Staff publish entries with animaguru library publish --project ID (--asset ASSET_ID | --character SLUG) --title … --summary … --description … --labels …, and edit or remove them with library update and library remove --yes.

Submit and share videos

Run animaguru auth login, then submit from a finished AnimaGuru video workspace:

animaguru submit --yes                            # Builds and hosts HTML5; private
animaguru submit --share "[email protected]" --yes  # Private review for a verified account
animaguru submit --file production/exports/film.mp4 --poster public/assets/cover.png --yes
animaguru submit --file production/exports/film.zip --dry-run

An optional positional directory selects the workspace; file and poster paths are relative to it. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.

MP4 subtitles: CLI 0.10.0 uploads an MP4's subtitles with it, and the AnimaGuru player shows them over the picture with a CC button to turn them off and a menu when there are several languages. The MP4 itself stays clean. With the default --subtitles auto, submit --file FILM.mp4 adds FILM.vtt (or else FILM.srt), which npm run export:mp4 writes beside it. --subtitles FILE chooses another .vtt/.srt file and --subtitles none skips them. The language comes from --subtitle-language, a WebVTT Language: header, the export receipt (FILM.json) or film.config.json. The file is checked before any video bytes are sent, and the dry run lists it. An MP4's width, height and duration now come from the MP4 itself and its default title from the export receipt, so another language's cut no longer takes the current film.config.json values. Burned-in --burn-captions exports have no subtitle files, so nothing is added. To add, replace or remove one language on an uploaded MP4:

animaguru videos subtitles VIDEO_ID --file production/exports/film-tr.vtt --yes   # language from the file or its export receipt
animaguru videos subtitles VIDEO_ID --file subtitles.srt --language de --yes
animaguru videos subtitles VIDEO_ID --remove de --yes

Each upload of up to 1 MiB is stored as WebVTT, up to 20 languages per video. HTML5 films draw their own captions and take no subtitle files. New subtitles on a public video send it back for staff review, like a new poster; removing a language does not.

To request public gallery publication, upload privately, open the video in My videos on the website, choose Share → Public, and accept the public video sharing agreement. Staff must approve the submission before anyone else can access its public link, download or embed. Direct CLI public-sharing requests without agreement acceptance are refused by the API.

videos list --scope mine|shared|public lists films. Owners can edit metadata, change visibility and replace recipients on the website, or use videos share VIDEO_ID --visibility private --share "[email protected]" --yes. videos delete VIDEO_ID --yes removes the film and files. Making a film private or removing a recipient revokes access to existing playback links.

Uploads are divided into SHA-256 verified 8 MiB parts. Interrupted submissions print their video ID: inspect with videos get VIDEO_ID, retry a fully uploaded film with videos complete VIDEO_ID, or delete the unfinished draft before resubmitting. Completion is idempotent. HTML5 ZIPs allow 64 MiB compressed / 96 MiB expanded with 500 entries and 32 MiB per asset; MP4s allow 512 MiB; PNG/JPEG/WebP covers allow 2 MiB. Uploads are available to verified accounts with a 2 GiB video library allowance. Hosting does not run paid generation jobs.

Upload directly to YouTube

CLI 0.9.0 adds animaguru youtube. Authorization and uploads run on your computer and call Google directly. You do not need an AnimaGuru account or a hosted video. The website, Worker, R2 and D1 are not involved.

Enable YouTube Data API v3 in your Google Cloud project, configure the Google Auth Platform consent screen and test users, and create an OAuth client of type Desktop app. Download its JSON file outside your project. A web OAuth client or Gemini API key will not work. The CLI uses Google's system-browser authorization with PKCE and a temporary 127.0.0.1 callback listener. Google app verification and quota rules apply. See Google's installed-app OAuth guide.

animaguru youtube auth login --client-file /absolute/path/desktop-client.json --yes
# Or, to also upload subtitles:
animaguru youtube auth login --client-file /absolute/path/desktop-client.json --captions --yes
animaguru youtube auth status
# --no-browser prints the URL; open it in a browser on this same computer.

Login requests youtube.upload to send videos and youtube.readonly to identify and verify your selected channel. Add --captions to also upload subtitle tracks: YouTube's caption API requires Google's broader youtube.force-ssl permission, which also allows managing your videos, so it is requested only with that flag. To add it to an existing connection, log out and log in again with --captions. --yes acknowledges YouTube's terms, Google's data use under its privacy policy, and local credential storage. Choose your own channel in Google's authorization screen. ANIMAGURU_YOUTUBE_CLIENT_FILE can supply the client-file path. To switch channels, disconnect first.

Export your animation with the existing npm run export:mp4 workflow, then use the saved MP4 path:

animaguru youtube upload --file production/exports/film-en.mp4 \
  --title "My film" --description "Made with AnimaGuru" \
  --privacy private --made-for-kids no --synthetic-media yes --dry-run
# After reviewing the file, destination and visibility, replace --dry-run with --yes.
animaguru youtube upload --file production/exports/film-en.mp4 \
  --title "My film" --description "Made with AnimaGuru" \
  --privacy private --made-for-kids no --synthetic-media yes --yes
animaguru youtube uploads list
animaguru youtube uploads resume UPLOAD_ID --yes
animaguru youtube auth logout --yes

Private is the default; --privacy unlisted|public changes it. You must choose --made-for-kids yes|no and --synthetic-media yes|no yourself. Follow YouTube's synthetic-content disclosure guidance; ordinary animation and realistic synthetic scenes can have different requirements. --channel CHANNEL_ID requires an exact match with your saved connection. Upload --yes confirms the destination, visibility and your rights to distribute the video. It does not spend AnimaGuru credits or submit it for AnimaGuru gallery review.

The optional positional directory sets the root for relative paths. The default title comes from the MP4's export receipt (FILM.json), then the film's film.config.json. --animation NAME selects a film in a multi-animation workspace. --file is required; export/rendering is a separate step. MP4s can be up to 256 GiB. Titles allow 100 characters and descriptions 5,000 UTF-8 bytes; neither may contain angle brackets. --dry-run checks the file and metadata without sign-in, uploads or network calls.

Subtitles: npm run export:mp4 writes FILM.srt and FILM.vtt beside FILM.mp4. With the default --captions auto, the upload adds the .srt (or else the .vtt) as a caption track once the video arrives. --captions FILE chooses another .srt/.vtt file and --captions none skips subtitles. The language comes from --caption-language, a WebVTT Language: header, the export receipt or film.config.json. The track has no name by default, like YouTube Studio uploads; --caption-name sets one. --dry-run lists the subtitle file and language. Without caption permission, a found subtitle file is skipped with a note, and an explicitly chosen one is refused before any video bytes are sent. If adding captions fails after the video arrives, the video stays, the JSON includes captionsError, and youtube uploads resume UPLOAD_ID --yes adds them later. Burned-in --burn-captions exports have no subtitle files, so nothing is added to them.

Thumbnail: when film.config.json sets "poster" (seconds), the export also saves that frame as FILM.jpg. With the default --thumbnail auto, the upload sets FILM.jpg (or .jpeg/.png) from beside the MP4 as the video's custom thumbnail; --thumbnail FILE chooses another JPEG or PNG up to 2 MiB and --thumbnail none skips it. This uses the upload permission, not --captions. YouTube allows custom thumbnails only on verified channels (https://www.youtube.com/verify); if it refuses, the video stays, the JSON includes thumbnailError, and youtube uploads resume UPLOAD_ID --yes retries after verification. Repeating an upload command for an already uploaded video adds subtitles or a thumbnail it does not have yet.

Uploads run while the CLI is running. Progress and instructions go to stderr; the final JSON includes the YouTube video ID, watch URL and actual returned privacy. Google may still be processing the video. A saved SHA-256 fingerprint guards resumption; restore the original file if it changes. Retries query Google's saved byte position, including after a lost final response. Interrupted transfers reuse their upload ID and session; starting another upload of the same unfinished file is refused. Repeating a completed upload with identical metadata returns its receipt. An expired session requires inspecting YouTube Studio before intentionally starting a new upload. See Google's resumable upload protocol.

Tokens, client configuration and resumable receipts stay under ~/.config/animaguru/youtube/, or ANIMAGURU_CONFIG_DIR/youtube/, in owner-only directories (0700) and files (0600). They are never included in command JSON or sent to AnimaGuru. Treat a backup of that directory as credentials. Receipts older than 30 days are removed on the next listing/upload. Authorization is refreshed and channel identity checked when used; revoked grants remove local authorized data. Logout revokes Google access and removes local credentials/receipts while keeping your MP4s and YouTube videos. If Google cannot confirm revocation, the CLI links to Google account permissions. Manage published copies in YouTube Studio.

Only one YouTube command may run at a time. Normal cancellation releases its lock. After a forced process kill, check that no YouTube command is running before removing youtube/operation.lock in the configuration directory.

Cloud sync and versions

CLI 0.11.0 adds animaguru cloud for Individual Pro and Team plans. It saves a video workspace, or a standalone video project, to AnimaGuru with every version. Use it to continue on another computer, work with your team and return to earlier versions. Personal cloud projects need your own Individual Pro or Team plan. A team's cloud projects need the team owner's Team plan, and every member can then save and download them.

animaguru auth login
animaguru workspaces use TEAM_ID              # optional: create the cloud project in a team
animaguru cloud link                         # creates a cloud project for this folder
animaguru cloud push -m "First cut"          # saves a version
animaguru cloud status                       # unsaved changes, and whether the cloud is newer
animaguru cloud pull                         # brings in versions saved elsewhere
animaguru cloud versions                     # newest first, with who saved each one
animaguru cloud restore VERSION --path animations/intro/src
animaguru cloud push                         # saves the restored files as the newest version
animaguru cloud clone PROJECT_ID my-films    # another computer; run npm install afterwards
animaguru cloud list

Run the commands anywhere inside the workspace; --dir PATH chooses another folder. What is not synced:

• node_modules/, dist/, production/exports/ and production/frames/;
• .env files except .env.example, .npmrc, *credentials*.json, *secrets*.json, keys and logs;
• anything matched by .gitignore or .animaguruignore;
• symbolic links.

Each version is a Git commit in the project's own Cloudflare Artifacts repository. Where a file is stored depends on its type, not its size:

• Media (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 20 GB for Individual Pro and 100 GB for each team.
• Work files (code, configs, briefs, JSON, SVG, fonts and everything else) are stored in Git at any size up to Artifacts' 32 MB per-file limit. A larger work file stops the push and is named; add it to .animaguruignore or move it.

The sync store lives in .animaguru/sync/, separate from any Git repository you keep for the folder, and linking adds it to .gitignore. Git credentials are short-lived and repository-scoped.

push refuses when the cloud has a newer version; pull brings it in first. Your other unsaved changes stay. When the same file changed on both sides, pull stops and lists it. Then:

• --prefer local keeps yours, and the next push replaces the cloud copy;
• --prefer cloud takes the cloud's, and keeps your copy in .animaguru/sync/backups/.

restore makes the folder, or the --path files and folders, match an earlier version without rewriting history. Push afterwards to save the result as the newest version. Replacing unsaved changes requires --yes and keeps backups.

Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, cloud projects stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. cloud unlink stops syncing a folder without touching the cloud. cloud delete PROJECT_ID --yes deletes the project, all its versions and its stored files. The studio's Cloud page lists projects, versions and their files, with downloads.

One brand, many animations

animaguru create workspace my-brand
cd my-brand
# Give the agent your official website or brand guide (or let it ask).
animaguru create animation product-launch
animaguru create animation how-it-works
npm run dev
npm run build -- --animation product-launch
npm run export:html -- --animation product-launch
npm run export:mp4 -- --animation product-launch
animaguru submit animations/product-launch --yes

The workspace installs dependencies, Codex/Claude skills, one PixiJS player and one export toolchain. Each animation folder keeps only its own config, scenes, story copy, media and production files. On the first creative request, the brand-kit skill uses a supplied official website or brand guide, or asks for one if the shared kit is still a placeholder. It researches first-party assets and guide pages, saves reusable files and a sourced branding/brand-guide.md, and fills branding/brand.json; the user can proceed with supplied assets or without a website. Later films reuse that identity. Root-level brand files can be referenced using workspace-relative paths. Only registered web assets travel with exports; brand guides remain local.

create animation NAME --workspace PATH works from another directory. The hub provides separate /animations/NAME/ player URLs and discovers new folders without a shared mutable project index. Export/review/build commands select a named film; outputs stay under that animation's production directory. submit --animation NAME selects a film from the root. Standalone create NAME and its commands remain supported.

For sound, put the final narration/mix in the selected film's public/assets/ and set its public-relative path in film.config.json. A configured soundtrack missing from the built package stops HTML5 export. Local originals/receipts in production/ are separate from playback assets. Normal Play uses sound; browser autoplay and frame capture stay muted.