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

# CLI overview

> Drive Melius canvases and generations from your terminal with the mel CLI.

`mel` is the Melius command-line interface — create projects and canvases, add nodes, wire edges, run generations across the latest image, video, audio, and language models, and download the results, all from your terminal or a script.

<Info>
  You authenticate with an API key. Create one in the Melius app under **Team settings → Integrations**. See [Installation](/cli/installation).
</Info>

## Built for agents, great for humans

`mel` is designed **agents-first** — every command returns structured JSON, uses deterministic exit codes, and needs zero interactive input, so an AI agent in a sandbox can drive it reliably. The same qualities make it pleasant in a terminal or a shell script: predictable output you can pipe through `jq`, and clear errors that tell you the exact command to fix them.

```bash theme={null}
npm install -g @melius-ai/cli

mel auth login --api-key mel_...
mel project list
mel node create <canvasId> --type image --prompt "a sunset over the ocean"
```

## How generations work

A generation in Melius **is a canvas node** — you create a node, start a run, and wait for it to finish:

```
mel canvas create <projectId>            → a canvas
mel node create <canvasId> --type image  → a node (prompt + optional model)
mel run start <nodeId> --canvas-id <id>  → start a run
mel run wait <runId>                     → block until finished
mel run download <runId>                 → a presigned URL for the output
```

Runs are **asynchronous** — `mel run start` returns a run id immediately and the generation happens in the background. `mel run wait` blocks until it's `finished` (or `failed`). To run an entire canvas in dependency order, use `mel bulk-run start <canvasId> --wait`.

## The output contract

Every command follows the same shape, which is what makes `mel` scriptable:

* **Success** → structured JSON on `stdout`, exit code `0`
* **Errors** → structured JSON on `stderr`, a [deterministic exit code](/cli/commands#exit-codes-and-errors)

Add `--text` for tab-separated human output, `--fields id,title` to project specific fields, or `--quiet` for exit-code-only. See [Global flags](/cli/commands#global-flags).

## Rate limits and credits

* **Credits.** Generations consume credits from the team you act on, exactly like the app. See each model's cost in `mel model list`.
* **Rate limits.** Requests are subject to a monthly per-plan limit. On a `429`, `mel` prints a notice to stderr and automatically backs off and retries, so polling commands ride through a limit instead of failing. Enterprise plans are unlimited.

## Next steps

<Columns cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install `mel`, create a key, and authenticate.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/cli/quickstart">
    Run your first generation end to end.
  </Card>

  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Every command, flag, exit code, and error shape.
  </Card>

  <Card title="Using mel from an agent" icon="robot" href="/cli/agents">
    JSON parsing, exit-code branching, and headless auth.
  </Card>
</Columns>