Masko CLI

Generate mascots, images, animations, and interactive canvases from the command line. Works standalone or with any AI agent that can run terminal commands.

Install

npx @masko/cli login

Your browser opens, you log in with your Masko account, and the API key is saved automatically. No key to copy-paste.

Or set the key manually:

export MASKO_API_KEY=masko_YOUR_API_KEY

Get your API key from the Developer dashboard.

Quick Start

# Check your credits (image = 1, animation = 5/sec)
masko credits

# List art styles
masko styles

# Create a project and mascot
masko projects create --name "My App"
masko mascots create --project PROJECT_ID --prompt "a friendly pixel art robot" --style pixel

# Generate an image
masko generate --mascot MASCOT_ID --type image --prompt "waving hello" --wait

# Generate an animation from scratch (creates image + animates in one step)
masko generate --mascot MASCOT_ID --type animation --prompt "waving happily" --duration 4 --wait

# Animate an existing pose (just pass the item ID)
masko generate --mascot MASCOT_ID --type animation --item ITEM_ID --prompt "gentle breathing" --duration 4 --wait

Tip

After generating an image, the CLI prints the exact command to animate it. Just copy and run.

Commands

Authentication

masko login                     # Open browser, log in, key saved automatically

Mascots

masko mascots create            # Create a mascot
  --project ID                    # Project ID (required)
  --prompt TEXT                   # Character description
  --style NAME                    # Art style (run masko styles to see options)
masko mascots list              # List all mascots
  --project ID                    # Filter by project
masko mascots get ID            # Get mascot details, items, and CDN URLs

Generation

masko generate                  # Generate image/animation/edit/logo
  --mascot ID                     # Mascot ID (required)
  --type TYPE                     # image | animation | edit | logo
  --prompt TEXT                   # What to generate (sets both pose + motion for animations)
  --image-prompt TEXT             # Pose description (animation from scratch)
  --animation-prompt TEXT         # Motion description (animation from scratch)
  --item ID                       # Animate/edit existing item (auto-resolves source)
  --duration N                    # Animation seconds (3-10, default 4)
  --wait                          # Wait for completion
  --json                          # Raw JSON output
  --name NAME                     # Name for the pose (e.g. "wave", "idle")

Jobs

masko jobs get ID               # Check job status
  --wait                          # Long-poll until completion (up to 120s)
  --timeout N                     # Custom timeout in seconds
masko jobs list                 # List recent jobs
  --mascot ID                     # Filter by mascot
  --status STATUS                 # pending | processing | completed | failed

Canvas

masko templates                 # List available canvas templates
masko canvas from-template      # Create canvas from a template
  --mascot ID --template ID
masko canvas generate-all       # Generate all canvas animations
  --mascot ID --canvas ID
  --duration N                    # Seconds per animation (default 4)

Utilities

masko credits                   # Check credit balance
masko styles                    # List all 38 art styles
masko projects create --name X  # Create a project
masko projects list             # List projects

Output Formats

By default, the CLI shows human-readable output. Add --json for raw JSON (useful for piping or when AI agents parse the output):

# Human-readable
masko credits
# Total: 14678
# Subscription: 0
# Top-up: 14678

# JSON
masko credits --json
# {"data":{"subscription":0,"topup":14678,"total":14678}}

CDN URLs

Every generate command returns CDN URLs immediately - before the file is ready. These URLs serve a branded placeholder that swaps to the real file automatically when generation completes.

masko generate --mascot ID --type image --prompt "waving" --wait

# Output:
# CDN URLs (usable immediately):
#   image: https://assets.masko.ai/abc123/my-mascot/wave-d017.png
#   transparent_image: https://assets.masko.ai/abc123/my-mascot/wave-1b2c.png

Embed these URLs in your code right away. No need to wait.

Animation Tips

From scratch (21 credits for 4s): --prompt sets both the pose and the motion. Use --image-prompt and --animation-prompt separately if you want different descriptions.

# Simple (same description for pose and motion)
masko generate --mascot ID --type animation --prompt "waving hello" --duration 4 --wait

# Specific (different pose vs motion)
masko generate --mascot ID --type animation \
  --image-prompt "standing with right hand raised" \
  --animation-prompt "waving hand back and forth" \
  --duration 4 --wait

From existing image (20 credits, saves 1): Pass --item and the source image is auto-resolved.

masko generate --mascot ID --type animation --item ITEM_ID --prompt "breathing gently" --duration 4 --wait

Animations loop by default. Pass --loop false to disable.

Credit Costs

Type	Cost
Image	1 credit
Animation	5 credits/second
Edit	1 credit
Logo	5 credits

Free: background removal, format conversion (webm/hevc), size variants.