mascot-design

Pull your Mascot Design mascots and their asset kits into any project — built for AI coding agents (Claude Code, Codex) and humans alike.

The CLI is a pure data plane: it downloads the assets you created in the web app, plus a machine-readable manifest.json and an integration-brief.md that tells your AI agent exactly how to build the mascot component. It never generates assets and never edits your app code.

Quick start

1. In Studio → Profile → API keys, create a key. The dialog shows a ready-to-paste command:

   npx mascot-design@latest login --key msk_…

2. See what you have, then pull a mascot into your project:

   npx mascot-design list
   npx mascot-design pull pixel-fox ./public/mascots

3. Hand integration-brief.md to your AI agent (or follow it yourself) to build the component.

For AI agents

Paste this into Claude Code / Codex after creating a key:

Connect to my Mascot Design account by running npx mascot-design@latest login --key <KEY> (I'll paste the exact command from Studio). Then npx mascot-design list --json, pull the mascot I pick with npx mascot-design pull <slug> ./public/mascots --json, read manifest.json and integration-brief.md from that folder, and implement the mascot component in this app following the brief.

Agent-friendly contract:

• --json prints machine output on stdout; all logs go to stderr.
• Exit codes: 0 ok · 1 unexpected · 2 auth · 3 not found / ambiguous slug · 4 partial download (failed files listed under skipped in manifest.json; re-run to retry).
• Auth resolution: --key > MASCOT_API_KEY > config file. Config lives at ~/.config/mascot-design/config.json (0600). The CLI talks to api.mascot-design.app; MASCOT_API_BASE / --api-base exist only as self-host/dev overrides.

Commands

| Command | Description | | --- | --- | | login [--key msk_…] [--api-base <url>] | Validate and save credentials | | whoami [--json] | Show the signed-in account and plan | | list [--json] | List your mascots (slug, name, style, id) | | pull <mascot> [dir] [--all] [--images-only\|--videos-only] [--force] [--json] | Download a mascot's asset kit |

pull accepts a mascot id or slug and defaults dir to ./<slug>/. By default it fetches the current version of every asset slot; --all includes superseded versions. Existing files are kept unless --force.

What lands on disk

pixel-fox/
  pixel-fox-turnaround-front.png     ← stills (transparent PNG)
  pixel-fox-idle.webm                ← animation clips (VP9 + alpha)
  …
  manifest.json                      ← machine-readable inventory
  integration-brief.md               ← instructions for your AI agent

manifest.json carries the mascot's identity (name, slug, palette, personality, animation states) and one entry per file with media type, format, transparency, dimensions, and provenance ids.

Keys and security

Keys are read-only, shown once at creation, stored server-side as a hash, and revocable from Studio at any time. Requests are rate-limited per key. Treat a key like a password: prefer MASCOT_API_KEY over flags in shared shells.