Skip to content
Masko logomasko
Docs
TerminalAPI reference
Documentation

A mascot from your terminal

Show a character on your Mac and connect it to your scripts. The masko command talks to a native background renderer, so the mascot stays on screen after the command exits.

Install Masko

Requires macOS 14 or later on Apple Silicon.

curl -fsSL https://releases.masko.ai/cli/install.sh | sh

This installs the signed, notarized CLI and background renderer. No Xcode, Node.js, or source checkout is required. If the installer asks you to add Masko to your PATH, add this line to ~/.zshrc, then open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

The command is installed at ~/.local/bin/masko; versioned builds live in ~/.masko/versions/. An existing installation from another installer is preserved. Intel Macs, Windows, and Linux are not supported by this release.

Update or choose a version

Run the install command again to get the latest version. Older builds are kept, and your sign-in and downloaded mascots are preserved. After updating, run masko host stop to close the old background renderer, then show your mascot again.

To install a specific version, including an earlier version:

curl -fsSL https://releases.masko.ai/cli/install.sh | MASKO_VERSION=0.1.0 sh
masko --version

Show Ko

masko show ko --name ko
masko state working --name ko
masko play celebrate --name ko --wait

Ko appears, starts working, then celebrates and returns to working. state holds an activity until you replace it. play performs a temporary reaction and returns to the latest state. show, state and play return immediately after acceptance while loading and animation continue. --wait waits for the whole performance, including its return; on show, it waits for the first visible frame.

ko loads the current Ko version. Use ko@11 to require version 11 while it is the served marketplace version. Public Ko does not require login. The first show downloads hosted media; later playback uses the local cache.

Connect a build result

Run this in your project after showing Ko:

masko state working --name ko
if npm run build; then
  masko play celebrate --name ko --wait
else
  masko state attention --name ko
fi

Your script decides which command to send. Available states depend on the character: use masko inspect --name ko --json to inspect Ko’s supported inputs.

Move, hide, and close

masko size 180 --name ko
masko hide --name ko
masko show --name ko
masko stop --name ko

You can drag the mascot or use its native menu. Hiding pauses playback; showing resumes it. Stopping disposes the instance. masko host stop closes every instance in the shared host.

Next steps