Command reference

Run mel --help or mel <group> --help at any time for the same reference in your terminal. Every command that creates a resource auto-generates a UUID if you don’t pass --id, and returns the created object as JSON.

Authentication

Command	Description
`mel auth login --api-key <key>`	Store and validate an API key in `~/.mel/config.json`
`mel auth logout`	Clear stored credentials
`mel auth whoami`	Show the current user (id, name, email)
`mel auth create-key --name <name>`	Create a new API key (raw key shown once)
`mel auth list-keys`	List keys for the current team
`mel auth revoke-key --key-id <id>`	Revoke an API key (takes effect immediately)

Teams

Command	Description
`mel team list`	List the teams your key can act on (find a `teamId` here)
`mel team current`	Show the active team
`mel team switch <teamId>`	Set the active team

Projects

Command	Description
`mel project list`	List projects in the current team
`mel project get <id>`	Get a project by id
`mel project create --title <t>`	Create a new project

Canvases

Command	Description
`mel canvas create <projectId>`	Create a canvas (returns the `id` used by every later command)
`mel canvas list <projectId>`	List canvases in a project
`mel canvas get <canvasId>`	Get canvas metadata
`mel canvas content <canvasId>`	Primary read — live canvas state; add `--node-id` and `--include-all-versions` to inspect one node plus its edges
`mel canvas plan-layout <canvasId>`	Compute positions for planned nodes (read-only)
`mel canvas delete <canvasId>`	Delete a canvas and all its content

Nodes

Node mutations write directly to the live canvas — changes sync to connected browser clients in real time.

Command	Description
`mel node create <canvasId> --type <t>`	Add a node. Types: `text`, `image`, `video`, `file`, `group`
`mel node bulk-create <canvasId> --json -`	Create multiple nodes and edges in one call
`mel node update <canvasId> <nodeId>`	Update fields (prompt, title, geometry, model)
`mel node delete <canvasId> <nodeId>`	Remove a node and its orphaned edges
`mel node get <canvasId> <nodeId>`	Read a persisted node (prefer `mel canvas content` for live state)
`mel node set-version <nodeId> --version-id <id>`	Switch the active output version
`mel node group <canvasId> --node-ids <ids>`	Group existing nodes (computes the bounding box)
`mel node ungroup <canvasId> <groupId>`	Ungroup and delete the group

mel node create options:

--type <type>        REQUIRED. text, image, video, file, group
--id <uuid>          Auto-generated if omitted
--title <title>      Defaults to the type name ("Image", "Text", …)
--prompt <text>      Text prompt
--model <m>          Model name (requires --variant)
--variant <v>        Model variant (requires --model)
--aspect-ratio <r>   21:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:21
--duration <n>       Output duration in seconds (video only)
--x --y --w --h      Geometry (sensible defaults per type)
--z-index <n>        Stacking order
--group-id <uuid>    Parent group

mel node update takes the same options (all optional); geometry must be updated as a full set (--x --y --w --h together).

Edges

Command	Description
`mel edge create <canvasId> --src <id> --dst <id> --type <t>`	Connect two nodes. Types: `text`, `image`, `video`, `file`
`mel edge bulk-create <canvasId> --json -`	Create multiple edges at once
`mel edge delete <canvasId> <edgeId>`	Remove an edge

Edge type determines data flow — an image edge passes the source node’s image output to the destination.

Runs

A run generates the output for a single node.

Command	Description
`mel run start <nodeId> --canvas-id <canvasId>`	Start a generation. Returns `{ id }`
`mel run get <runId>`	Status: `pending`, `running`, `finished`, `failed`
`mel run wait <runId>`	Block until done. Exit `0` = finished, `1` = failed, `4` = timeout
`mel run latest <canvasId>`	Latest run status for every node on a canvas
`mel run download <runId>`	Presigned URL for a finished run’s output
`mel run magic-resize <sourceNodeId> --canvas-id <id> --ratios <list>`	Resize a finished image into up to 5 aspect ratios in one call

Auto-model resolution. When --model/--variant are omitted, mel run start resolves the right model from platform defaults — including picking image-to-image when the node has an incoming image edge. --canvas-id is required so the CLI can verify the node and do edge-aware detection.

mel run start <nodeId> --canvas-id <canvasId>                               # auto
mel run start <nodeId> --canvas-id <canvasId> --model flux-pro --variant text-to-image

Bulk runs

Run an entire canvas in dependency order.

Command	Description
`mel bulk-run start <canvasId>`	Run all nodes tier by tier. Add `--wait` to block, `--node-ids <ids>` to scope
`mel bulk-run get <bulkRunId>`	Status and per-node progress
`mel bulk-run wait <bulkRunId>`	Block until done. Exit `0` = finished, `1` = failed, `4` = timeout
`mel bulk-run download <bulkRunId>`	ZIP of leaf-node outputs → `{ url, filename, size }`

Downstream nodes wait for their inputs; if a node fails, its dependents are skipped while independent branches continue.

Presets

Presets are pre-built canvas templates (nodes, edges, and groups).

Command	Description
`mel preset list`	List available presets
`mel preset apply <canvasId> <presetId>`	Create all of a preset’s nodes, edges, and groups with proper layout

Models

Command	Description
`mel model list --category <text\|image\|video>`	Discover models, modes, aspect ratios, and credit costs
`mel model defaults`	Show the auto-model defaults per node type

Audio & fonts

Command	Description
`mel audio voice list`	List available ElevenLabs voices for text-to-speech and audio-to-audio nodes
`mel font list`	List the team’s uploaded custom fonts (for the `better-font-32b` image model)

Comments

Command	Description
`mel comment list <canvasId>`	List comment threads
`mel comment create <canvasId> --body <text> --x <n> --y <n>`	Start a thread at a canvas position
`mel comment reply <threadId> --body <text>`	Reply to a thread
`mel comment resolve <threadId>`	Mark a thread resolved

Presence

Show the agent’s live “working here” region on a canvas — visible in real time to everyone with the canvas open.

Command	Description
`mel presence claim <canvasId>`	Claim a region — `--node-ids <ids>` for existing nodes, `--bounds <x,y,w,h>` for empty space
`mel presence release <canvasId>`	Release the claim (the overlay disappears for all viewers)

Assets

Search your team’s Files library (past uploads and generations) and place existing assets onto a canvas by reference — no re-upload, no duplicate. Requires a Pro or Enterprise plan.

Command	Description
`mel asset search <query>`	Semantic search of the team library, exact filename/title matches first. Returns up to 5 matches, each with `assetId`, `filename`, `fileType`, and preview URLs
`mel asset place <canvasId> <assetIds...>`	Place existing assets onto a canvas by `assetId` (up to 10) — references the original asset and returns the created file `nodeId`s

mel asset search options:

--limit <n>          Max results, 1–5 (default 5)
--file-type <type>   Filter by media type: image, video, audio, pdf, text
--canvas-id <id>     Scope to one canvas's assets (filename match within it);
                     omit to search the whole team library by meaning

mel asset search returns assetIds — feed them straight into mel asset place, then wire the resulting nodes into generations with mel edge create:

mel asset search "black jacket shot" --file-type image
mel asset place <canvasId> <assetId1> <assetId2>

Uploads

Upload adds a new local file; mel asset search reuses one already in the team library.

Command	Description
`mel upload <filePath>`	Upload a local image → `{ assetId, url, … }`
`mel upload <filePath> --node-id <id>`	Upload and link to an existing node
`mel upload <filePath> --canvas-id <id>`	Upload and associate with a canvas

Supported formats: PNG, JPEG, GIF, WebP, AVIF. Video must be generated on the canvas, not uploaded.

Configuration

Command	Description
`mel config get [key]`	Show all config, or one key
`mel config set <key> <value>`	Set `apiKey`, `baseUrl`, or `teamId`
`mel config path`	Print the config file path (`~/.mel/config.json`)

Shell completion

Command	Description
`mel completion bash`	Print a bash completion script
`mel completion zsh`	Print a zsh completion script
`mel completion fish`	Print a fish completion script

Generated from the live command tree, so completions never drift. See Installation → Shell completion for one-line setup per shell.

Global flags

Available on every command:

--json             JSON output (default)
--text             Tab-separated plain text
--fields <csv>     Select specific fields, e.g. --fields id,title,status
--quiet            Suppress output, exit code only
--verbose          Log request/response metadata to stderr (never your key)

Exit codes and errors

mel uses deterministic exit codes so scripts and agents can branch on the result without parsing text:

Code	Meaning	What to do
`0`	Success	Parse stdout
`1`	API error (4xx/5xx)	Read the error message
`2`	Usage error (bad args)	Fix the command
`3`	Auth error (401/403)	Re-authenticate or check the team
`4`	Timeout	Retry or raise `--timeout`
`5`	Network error	Check connectivity

Errors are structured JSON on stderr:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key",
    "status": 401,
    "suggestion": "Run: mel auth login --api-key <key>"
  }
}

Every error carries a machine-readable code, a human-readable message, and usually a suggestion with the exact command to fix it.

Rate limiting

The API is rate limited per plan. On a 429, mel prints Rate limited — waiting Ns… to stderr, honors the Retry-After header (or backs off exponentially), and retries — so polling commands like mel run wait ride through a limit. stdout stays clean. After repeated 429s it gives up with a RATE_LIMITED error (exit 1).

​Authentication

​Teams

​Projects

​Canvases

​Nodes

​Edges

​Runs

​Bulk runs

​Presets

​Models

​Audio & fonts

​Comments

​Presence

​Assets

​Uploads

​Configuration

​Shell completion

​Global flags

​Exit codes and errors

​Rate limiting