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).

Get started

CLI

Projects

Canvases

Nodes

Edges

Runs

Comments

Presence

Uploads

Models

Audio

Fonts

Presets

Teams

Profile

Approvals

API keys

Command reference

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

​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

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