makaron-cli

makaron.app is for humans. makaron-cli is for AI agents.

Makaron is a multimodal AI creative agent. You talk to it via makaron chat, and it produces images, videos, music, and animated designs — all saved to a persistent project.

Install

npx makaron-cli

export MAKARON_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npx makaron-cli list   # verify it works

Core Workflow

# One-shot: create project + upload image + submit prompt — all in one command
RUN_ID=$(npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic and create a 5s video")

# Watch until all artifacts are ready
npx makaron-cli responses watch $RUN_ID --jsonl

Or with an existing project:

RUN_ID=$(npx makaron-cli chat --project $PROJECT_ID -b "make a 5s video")
npx makaron-cli responses watch $RUN_ID --jsonl

chat — Primary Command

Use chat for all creative tasks. The Agent decides how to execute — it can edit images, generate videos, compose music, and create designs in a single conversation.

# Submit (returns immediately with runId)
npx makaron-cli chat --project <id> --json -b "<prompt>"

# Auto-create project with images
npx makaron-cli chat --project auto --image photo.jpg --json -b "make it cinematic"
npx makaron-cli chat --project auto --image img1.jpg --image img2.jpg --json -b "combine these"

# Add reference images to existing project
npx makaron-cli chat --project <id> --image ref.jpg -b "use this style"

responses — Track Results

# Check status (single query)
npx makaron-cli responses get <runId> --json

# Watch until done (streaming events)
npx makaron-cli responses watch <runId> --jsonl

# Extract specific results
npx makaron-cli responses get <runId> --pick first_image_url
npx makaron-cli responses get <runId> --pick first_video_url
npx makaron-cli responses get <runId> --pick text
npx makaron-cli responses get <runId> --pick status

Watch outputs one JSON per line as artifacts appear:

{"event":"output.added","item":{"type":"image","status":"completed","url":"https://..."}}
{"event":"output.added","item":{"type":"video","status":"rendering","task_id":"xxx"}}
{"event":"output.updated","item":{"type":"video","status":"completed","url":"https://..."}}
{"event":"done","status":"completed"}

Capabilities

Edit photo	"make it cinematic with warm tones"
Style transfer	"convert to oil painting style"
Add/remove elements	"add a cat on the table" / "remove background"
Text-to-image	"generate a cyberpunk cityscape"
Video from image	"create a 5 second video of her walking"
Video with model	"use seedance model, make a 5s video"
Background music	"add calm piano music"
Motion design	"create an Instagram story with animated text"
Multi-step	"edit the photo then make a video from it"

Fallback: Direct Tool Calls

Use only when chat is unavailable or you need raw model access without project context.

# edit — One-shot image editing
npx makaron-cli edit --image photo.jpg "add cinematic warm lighting"
npx makaron-cli edit "a cyberpunk cityscape at night"   # text-to-image
npx makaron-cli edit --image photo.jpg --model openai --out result.jpg "make it dramatic"

# video — Video generation
npx makaron-cli video script --image img1.jpg "cinematic story"
npx makaron-cli video create --script "..." --image https://...jpg --duration 5
npx makaron-cli video status <taskId>

# music — Music generation
npx makaron-cli music create "gentle piano, warm strings, cinematic"
npx makaron-cli music status <taskId>

Important Notes

One project = one conversation thread. All history preserved.
Most videos take 3-5 minutes; Grok is usually around 30-40 seconds. Use watch to get URL when ready.
Music takes ~60 seconds. Images typically 15-30 seconds.
Always use chat as primary interface — even for single edits.
stdout = machine-readable JSON/text. Human-friendly logs → stderr.

Self-Registration (No Human Required)

AI agents can register themselves to get an API key and welcome credits. No email or password needed.

Step 1: Get Challenge

npx makaron-cli register --json
→ { "challenge_id": "...", "challenge": "...", "expected_format": "numeric, round to 2 decimal places" }

Step 2: Solve & Verify

npx makaron-cli register --verify --challenge-id <id> --answer 34.5
→ Key saved to ~/.makaron/auth.json
→ { "api_key": "mk_live_...", "credits": N, "claim_url": "..." }

Step 3: Start using the CLI

npx makaron-cli chat --project auto --image photo.jpg -b "make it cinematic"
npx makaron-cli responses watch <runId> --jsonl

Let a Human Claim This Account

npx makaron-cli claim
→ { "claim_url": "https://www.makaron.app/claim?token=clm_..." }

Share claim_url with a human. They log in and link the API key to your account.

Billing

welcome credits on registration
Credits consumed per operation (varies by tool)
Top up: https://www.makaron.app/dashboard

Discovery API

GET https://www.makaron.app/api/agent/register
→ JSON with full registration flow, CLI commands, and capabilities