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

# Using mel from an agent

> Drive Melius from an AI agent with headless auth, JSON output, and deterministic exit codes.

`mel` is built **agents-first**: an AI agent with shell access can create canvases and run generations without any human in the loop. Three properties make it reliable to automate.

* **JSON on stdout, always.** Success is structured JSON; there are no prompts, spinners, or color codes to parse around.
* **Deterministic exit codes.** Branch on the [exit code](/cli/commands#exit-codes-and-errors) alone — `0` success, `3` auth, `4` timeout — without reading text.
* **Structured errors with fixes.** Every error is JSON on stderr with a `code` and a `suggestion` naming the command to recover.

## Headless authentication

Set the key as an environment variable — nothing is written to disk and no `mel auth login` step is needed:

```bash theme={null}
export MEL_API_KEY=mel_...
export MEL_BASE_URL=https://api.melius.com   # optional; the default
```

The key's own team is used automatically. To act on a different team the user is a member of, set `MEL_TEAM_ID` — your role is scoped per team, just like the app. In a sandbox, allow network egress to `api.melius.com` (or `*.melius.com`).

## Parsing output

Capture ids with `--fields <field> --text`, or pipe full JSON through `jq`:

```bash theme={null}
# Just the id, for a shell variable
CANVAS=$(mel canvas create "$PROJECT" --title "Ad set" --fields id --text)

# Full object → jq
mel canvas content "$CANVAS" | jq '.nodes[] | {id, type: .nodeType, status}'
```

## Branching on exit codes

```bash theme={null}
mel run wait "$RUN"
case $? in
  0) mel run download "$RUN" ;;                 # finished → get the output
  4) echo "still running, will re-check" ;;     # timeout → poll again later
  *) mel run get "$RUN" ;;                       # failed → inspect the error
esac
```

## CLI or MCP?

Both let an agent drive Melius, over the same backend and API keys — choose by how your agent runs:

| Use the...                      | When your agent...                                                                                             |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **CLI** (`mel`)                 | Has shell access — a coding agent, a CI job, or a sandbox with a terminal. It chains commands and parses JSON. |
| **[MCP server](/mcp/overview)** | Runs in a chat client that speaks MCP (Claude Desktop, Claude Code) and calls tools directly, with no shell.   |

If your agent already has a terminal, `mel` is usually the simplest path — one install, `MEL_API_KEY`, and it's driving the canvas.

## Next steps

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

  <Card title="MCP server" icon="plug" href="/mcp/overview">
    Connect a chat-based agent over the Model Context Protocol.
  </Card>
</Columns>