Command reference - Melius docs

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 or post-processes the output for a single node.

Command	Description
`mel run start <nodeId> --canvas-id <canvasId>`	Start a generation. Returns `{ id }`
`mel run tool <nodeId> --canvas-id <canvasId> --tool remove-background`	Remove a finished image’s background in place. 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

Node tools. mel run tool post-processes a node’s finished asset and creates a new active version on the same node. The currently supported tool is remove-background for image nodes and file nodes that contain images. It costs 12 credits.

RUN=$(mel run tool <imageNodeId> --canvas-id <canvasId> --tool remove-background --fields id --text)
mel run wait "$RUN"
mel canvas content <canvasId> --node-id <imageNodeId> --include-all-versions

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 layouts (nodes, edges, and groups) expanded onto the canvas so you can see and edit every node.

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

Templates

Templates are opaque, reusable canvas workflows. Applying one drops a single collapsed box onto the canvas that exposes only its public input/output ports — the internal workflow stays private.

Command	Description
`mel template list`	List available templates with their `id`, title, declared `inputPorts`/`outputPorts`, and `estimatedCreditCost`
`mel template apply <canvasId> <templateId>`	Apply a template as one collapsed box — returns its `instanceId` and `groupId`

mel template apply options:

--center-x <n>       X center for the box (auto-placed if omitted)
--center-y <n>       Y center for the box (auto-placed if omitted)
--inputs <json>      JSON array of text, library-asset, or media-URL inputs targeting port IDs

Each input targets a portId from mel template list and is one of:

Text — { "kind": "text", "portId": "<id>", "text": "…" }
Library asset — { "kind": "asset", "portId": "<id>", "assetId": "<id>", "mediaType": "image|video|audio|pdf" } — an asset already in your library (find one with mel asset search)
Media URL — { "kind": "assetUrl", "portId": "<id>", "url": "https://…", "mediaType": "image|video|audio|pdf" } — Melius fetches the URL and stores it as an asset, so you can use an image or video already hosted elsewhere without uploading it first

Beta — media-URL (assetUrl) inputs are rolling out gradually. Reach out to support if you’d like access.

After applying, run the box with mel bulk-run start <canvasId> --node-ids <groupId> --wait:

mel template list
# Wire an image already hosted on your site straight into a template port
mel template apply <canvasId> <templateId> \
  --inputs '[{"kind":"assetUrl","portId":"image","url":"https://example.com/photo.jpg","mediaType":"image"}]'
mel bulk-run start <canvasId> --node-ids <groupId> --wait

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 20 matches per page, each with `assetId`, `filename`, `displayName`, `fileType`, `contentType`, and preview URLs
`mel asset folders`	List the team’s Files folders (`id`, `name`, `path`, `fileCount`) — resolve a folder name to an `id` for `--folder-id`
`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 per page, 1–20 (default 20)
--offset <n>         Skip the first N matches to page deeper (default 0)
--file-type <type>   Filter by media type: image, video, audio, pdf, text
--source <source>    Filter by asset source: upload or generated
--canvas-id <id>     Scope to one canvas's assets (filename match within it)
--folder-id <id>     Scope to one folder and its subfolders (from mel asset folders)
--tags <names>       Filter to assets carrying ALL of these tags (comma-separated)

The query is optional when you pass --folder-id or --tags — omit it to bring in a whole folder or every tagged asset. The response is { query, total, results }; page through total with --limit and --offset. 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 folders                                   # find a folder id
mel asset search --folder-id <folderId>             # bring in a whole folder
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

There is no monthly request quota on any plan, but a burst of requests can still be rate limited. 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

​Templates

​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

Templates

Models

Audio & fonts

Comments

Presence

Assets

Uploads

Configuration

Shell completion

Global flags

Exit codes and errors

Rate limiting