Desktop commands

Install Masko first. The runtime currently supports macOS 14+. Control commands use the local host; they do not generate new media or spend generation credits.

Everyday controls

Command	Result
`masko show acme/bob --name bob`	Prepare and show the current complete canvas, without release.
`masko show acme/bob --canvas gaming --name bob`	Select an existing canvas by name or ID.
`masko show ko --name ko`	Show the current Ko version.
`masko state working --name ko`	Hold an ongoing activity until replaced.
`masko state clear --name ko`	Release the held state and return to the character’s default.
`masko play celebrate --name ko --wait`	Play a reaction and wait for its complete return.
`masko play celebrate --instant --name ko`	Jump directly into the performance, skipping its entry transition.
`masko cancel --name ko`	Request the authored return path from the current performance.
`masko hide --name ko`	Hide and pause.
`masko show --name ko`	Resume the existing instance.
`masko stop --name ko`	Close and dispose this instance.

show, state, play and prepare return as soon as the host accepts them. Media loading and animation continue after the terminal prompt returns. They can be issued sequentially without waiting for show to finish loading.

Add --wait to wait explicitly: show waits for its first frame, state for preparation/application, prepare for all media, and play for the full performance and return. State application does not wait for visual transitions to finish. --timeout SECS limits these waits (default: 300). Control+C stops waiting while accepted work continues.

state clear replaces pending state requests. An active play finishes normally, then returns to the default pose. state rest remains supported. Use state behavior::clear if the character has an authored behavior named clear.

A second simultaneous play returns busy, including while the first is preparing. Changing state during a performance updates where the mascot returns afterwards. cancel follows the character’s animation path; it is not an immediate frame cut.

--instant still plays the authored performance and its return path. It does not bypass media loading or make the command wait. Combine it with --wait when you need completion.

Names and supported inputs

masko inspect --name ko --json
masko status --name ko --json
masko instances --json

Character references and instance names serve different purposes. ko selects the current hosted character; ko@11 requires version 11. --name ko identifies a running copy on your machine.

Bare state and play names resolve to behavior::NAME. Use the full name for an action:

masko play action::papercraftGift --name ko --wait

Inspect the character’s capabilities before inventing new names. An animation must exist in its authored graph before a command can play it.

Two independent mascots

masko show ko --name left --x 300 --y 100
masko show ko --name right --x 650 --y 100
masko state working --name left
masko play celebrate --name right --wait

The shared host supports up to 16 instances. Coordinates are macOS screen points, measured from the bottom-left; positions are clamped to a visible display. masko size 180 --name left sets the size in points, from 64 to 720.

Preparation and diagnostics

Command	Result
`masko prepare --name ko`	Download the graph’s media ahead of playback.
`masko host status`	Inspect the shared renderer.
`masko host start`	Start it explicitly; showing a mascot also starts it.
`masko host stop`	Close all hosted mascots and stop the renderer.

masko status --json includes request IDs, progress and background errors. Pending requests can be queued or running; finished requests are completed, failed or cancelled. Play preparation completes before the animation does; completed_plays records its full return. The last 128 requests are kept until the instance is stopped. A newer pending state supersedes the previous one, hide prevents pending show from displaying, and stop prevents an in-flight load from reopening the mascot.

Host logs are at ~/Library/Application Support/MaskoDeveloper/host.log. Instances are not restored after a host restart. If you lose a command response, inspect status before submitting another performance.

An acceptance receipt is not a guarantee that loading succeeded. Use masko show acme/bob --name bob --wait to surface a loading failure directly, or check masko status --name bob --json after an ordinary show. If the canvas is incomplete, version_not_ready is a failure, not a subscription to future generation. Finish generating its media, then issue show again.

A loaded mascot keeps its snapshot while you edit or regenerate its canvas. To load the finished edits, stop that instance and show the character again. media_ready describes the renderer's current media; it is separate from a cloud run's readiness. Repeating the same loop preserves the loaded media rather than preparing it again at each boundary.

Use --json for machine-readable output. Diagnostics go to stderr. Cloud job watchers emit newline-delimited JSON; see generation and recovery.