Create and animate

The CLI edits the same hosted collection and canvas as the Masko app. Start with an appearance, add a reaction, review the images, then generate the animations.

These authoring commands require the matching developer backend. Check the deployed OpenAPI specification for /v1/characters and /v1/runs. For a local backend, set MASKO_API_URL=http://localhost:3000/api/v1 before signing in.

masko login
masko create acme/bob --prompt "A tiny orange robot with rounded hands"

Choose a name such as acme/bob. The acme prefix names the project created for this character; it does not switch your authenticated workspace. Browser login determines the personal or team workspace that owns the work and pays for generation. For a remote terminal, use masko login --device --no-browser. API keys can be supplied with MASKO_API_KEY or masko login --api-key; keep them out of committed files.

Creation writes a draft with an idle pose and loop prompt. It does not generate images or videos. In an existing project, masko init --character acme/bob selects a hosted character for subsequent commands.

Choose an appearance

masko generate reference --count 4
masko assets --type image
masko reference select ASSET_ID

Generation costs credits and asks for approval. Inspect the candidates and replace ASSET_ID with the chosen image’s ID. To use your own image, run masko reference add ./character.png and select the resulting asset.

Add a reaction, then review it

masko add celebrate --description "Jumps and throws confetti"
masko generate images
masko open

add proposes the appearance and movement prompts for review. It generates no media itself. You can supply all four prompts with --image, --loop, --enter, and --exit to skip the suggestion step. For ongoing activities use --playback held; temporary performances use --playback once.

Review the poses in the app before generating motion:

masko generate animations

Show the completed character with masko show acme/bob --name bob. No release step is required. Add --canvas gaming to select an existing canvas by name. Masko validates its graph and media, then creates or reuses a private runtime snapshot. Missing media returns version_not_ready; show never starts generation or spends credits.

Automate with a credit ceiling

masko plan --targets images --json
masko generate --plan PLAN_ID --max-credits 100 --json
masko jobs watch RUN_ID --json

Review the plan and replace PLAN_ID. Plans list missing work, reused assets, prompts, and estimated credits without spending credits. They expire after one day. Execution checks the graph revision and your credit ceiling again.

Keep the returned RUN_ID. Accepted work continues if your terminal disconnects. Ctrl+C stops watching, not the cloud run. --detach returns after acceptance without watching; --json supports automation.

Recover and download

masko jobs show RUN_ID --json
masko logs RUN_ID --cursor 0 --json
masko assets --run RUN_ID --json
masko assets download --run RUN_ID --output ./outputs

Watchers emit NDJSON events with sequence cursors. An empty page does not mean the run is finished. Exit codes are 0 for success, 1 for failure, 124 for timeout, and 130 for interruption.

Reference runs can finish while awaiting your selection; image runs can finish while awaiting animation generation. Completed source videos may still need transparent derivatives before the character is playable.

Follow progress without starting another generation:

masko logs RUN_ID --follow

Progress messages distinguish “Generating the source video”, background removal and transparent WebM export, HEVC export for macOS, and completed transparent videos. These are processing stages, not a percentage or an estimated time remaining. A source video being ready does not mean the mascot is playable; inspect the final run for readiness: ready.

masko jobs watch RUN_ID --json and masko logs RUN_ID --follow --json stream one JSON value per line. Preserve event sequence values and resume with --cursor SEQUENCE. Use masko jobs show RUN_ID --json for a single status document. One developer run can be active per canvas; separate canvases can generate concurrently. Starting another watcher only observes existing work and spends no credits.

To retry failed work explicitly:

masko jobs retry RUN_ID --failed --max-credits 100 --json

Review changes and cost before retrying. Successful work is retained. When only free media processing failed, inspect the repair plan and use --max-credits 0 to prevent new paid generation. Downloads preserve completed files and refuse to overwrite existing files.

Optional fixed version

masko release --json remains available when you explicitly want a version reference to pin, such as acme/bob@3. It is not required for show. A running instance keeps its snapshot; stop and show it again to load edits. Keep authoring credentials out of distributed apps. Use customer mascot access to have your backend issue a temporary URL for the SDK; that guide includes deployment availability.

See hosted characters and runs for the REST contract, idempotency, graph edits, and readiness fields.