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
mel run start <videoNodeId> --canvas-id <canvasId> --post-process video-gif   # convert the finished clip to a GIF

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 runs Pixelcut (20 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, `--post-process video-gif` to convert the final clip to a GIF, `--match-clip-length-to-audio <ids>` to size clips that play their audio as recorded to that audio, and `--start-clips-together` to start clips fed by chained script nodes at once after the scripts finish
`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. When you set a team with mel team switch <teamId> or MEL_TEAM_ID, mel template list puts templates targeted at that team before global templates. Apply the returned id to use that team’s current workflow.

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; page with `--cursor <nextCursor>`
`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)

Pass --agent-name <name> to mel presence claim to name the agent shown on the claim overlay. Pass the same --presence-id <uuid> to mel presence claim and mel presence release to keep your overlay separate from other agents working on the same canvas. mel presence release prints removed: false when no overlay with that ID was showing. A claim you never release disappears on its own five minutes after your last request to Melius.

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)
--cursor <cursor>    Continue from a previous result's nextCursor (same query and filters)
--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. Every filter applies together. The response is { query, total, results, hasMore, nextCursor }; while hasMore is true, pass nextCursor to --cursor with the same query and filters for the next page. 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).

Sticky notes

mel canvas content <canvasId> includes a notes array with note text, geometry, group membership and height mode. Use --note-id <noteId> to inspect one note, or --note-offset 0 to read notes in pages of 50; continue with nextNoteOffset until it is null. Positions are relative to the parent group when groupId is set.

mel note create <canvasId> --body "Alex" --x 0 --y -80 --width 1040 --height 80 --height-mode manual
mel note update <canvasId> <noteId> --body "Alex — character sheets" --width 1200
mel canvas content <canvasId> --note-id <noteId>

Both write commands require editor access and return the saved note. Updates preserve omitted fields, group membership and styling. Use --height-mode manual for a fixed-height name bar; auto fits the text.

​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

​Sticky notes

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

Sticky notes