Command line reference
Run masko help, masko help commands or masko COMMAND --help for the same text offline. Every command accepts --json.
Account
| Command | Result |
|---|---|
masko login | Sign in through your browser. Options: --no-browser, --device, --api-key, --api-key-stdin, --scope read|write, --name NAME, --timeout SECS. See CLI login. |
masko whoami | Show your account, workspace name, access (read or write), sign-in method and credits. |
masko credits | Show total, subscription and top-up credits. |
masko feedback "TEXT" | Send feedback to the Masko team. Pipe longer notes in: cat notes.txt | masko feedback. The first line is the summary (up to 500 characters), 8,000 characters in all; 5 a minute and 30 a day. Read-only logins work. |
masko logout | Sign out on this Mac and revoke the session. If Masko cannot be reached, the login is still removed here; revoke it under Signed-in computers. An API key set in MASKO_API_KEY still applies. |
masko login --api-key asks for a key at a hidden prompt; --api-key-stdin reads it from stdin, for automation. Neither creates a key: get one at API keys.
Masko API
masko studio METHOD PATH [--file FILE] [--idempotency-key KEY] [--json]| Part | Use |
|---|---|
METHOD | GET, POST, PUT, PATCH or DELETE. |
PATH | A /v1 path from the API reference, such as mascots, jobs/JOB_ID?wait=true or canvases/CANVAS_ID/generate-all. /v1/... and full https://api.masko.ai/v1/... links, such as a job's poll_url, work too. Quote paths with ? or &. Sign-in (auth), admin and the old collections paths are refused. |
--file FILE | The JSON request body, or - to read it from stdin. For upload, an image or video file instead: PNG, JPEG, WebP, GIF, SVG, MP4, MOV or WebM. |
--idempotency-key KEY | Every POST sends one. Reuse the key a failed or interrupted POST printed, and Masko never runs or charges it twice. |
Requests send Masko-API-Version: 2026-09-26, so field names match the docs and the MCP server (mascot_id, not collection_id). The output is the API's response: data, plus meta.pagination (total, has_more, next_cursor) for lists. A DELETE that returns nothing prints Done. on stderr.
To see a canvas's cost before generating, call GET canvases/CANVAS_ID/generation-estimate, or generate-all with "dry_run": true, then pass max_credits. Talking animations take "dry_run": true too; see talking.
Assets
| Command | Result |
|---|---|
masko assets show ASSET_ID | Show one asset. |
masko assets download ASSET_ID --output PATH | Save one asset as the new file PATH, in a folder that exists. --format selects original or the asset type. Existing files are never overwritten. |
To list a mascot's assets, use masko studio GET 'assets?mascot_id=MASCOT_ID'.
Output and errors
| Exit code | Meaning |
|---|---|
0 | Done. |
1 | An error. With --json, it is printed on stdout as {"error": {"code", "message", ...}}; otherwise on stderr. |
124 | Timed out. |
130 | Stopped with Control+C. Work Masko already accepted may continue; a POST prints its idempotency key. |
Errors keep the API's fields: status, param (the field that was wrong), request_id (give it to support), doc_url, retry_after and, for a POST, idempotency_key. Unknown commands suggest the closest one. See errors.
Environment and global options
| Setting | Use |
|---|---|
--api-url URL or MASKO_API_URL | Select the backend, for local development. |
MASKO_API_KEY | Use an API key. It overrides the saved login. An empty value counts as unset. |
MASKO_NO_UPDATE_CHECK=1 | Turn off the daily notice that a newer version is out. It is also off in CI and with --json. |
--json | Print JSON on stdout. |
--help, -h | Read help without connecting or changing anything. |
--version, -v, masko version | Print the CLI version. |