> ## Documentation Index > Fetch the complete documentation index at: https://docs.melius.com/llms.txt > Use this file to discover all available pages before exploring further. # Command reference > Every mel command, grouped by resource, plus global flags and exit codes. Run `mel --help` or `mel --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 ` | 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 ` | 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 ` | 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 ` | Set the active team | ## Projects | Command | Description | | -------------------------------- | --------------------------------- | | `mel project list` | List projects in the current team | | `mel project get ` | Get a project by id | | `mel project create --title ` | Create a new project | ## Canvases | Command | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `mel canvas create ` | Create a canvas (returns the `id` used by every later command) | | `mel canvas list ` | List canvases in a project | | `mel canvas get ` | Get canvas metadata | | `mel canvas content ` | **Primary read** — live canvas state; add `--node-id` and `--include-all-versions` to inspect one node plus its edges | | `mel canvas plan-layout ` | Compute positions for planned nodes (read-only) | | `mel canvas delete ` | 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 --type ` | Add a node. Types: `text`, `image`, `video`, `file`, `group` | | `mel node bulk-create --json -` | Create multiple nodes **and** edges in one call | | `mel node update ` | Update fields (prompt, title, geometry, model) | | `mel node delete ` | Remove a node and its orphaned edges | | `mel node get ` | Read a persisted node (prefer `mel canvas content` for live state) | | `mel node set-version --version-id ` | Switch the active output version | | `mel node group --node-ids ` | Group existing nodes (computes the bounding box) | | `mel node ungroup ` | Ungroup and delete the group | **`mel node create` options:** ``` --type REQUIRED. text, image, video, file, group --id Auto-generated if omitted --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. ```bash theme={null} 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 `assetId`s — feed them straight into `mel asset place`, then wire the resulting nodes into generations with `mel edge create`: ```bash theme={null} 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`](#assets) 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](/cli/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**: ```json theme={null} { "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 `429`s it gives up with a `RATE_LIMITED` error (exit `1`).