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

# Installation

> Install the mel CLI and authenticate with a Melius API key.

## Install

Install `mel` with npm or Homebrew:

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

  ```bash Homebrew theme={null}
  brew install melius-ai/tap/mel
  ```
</CodeGroup>

npm requires **Node.js 20 or later**; Homebrew (macOS and Linux) pulls Node in for you. Verify either way:

```bash theme={null}
mel --version
```

## Update

Check your installed version with `mel --version`, then upgrade with the **same tool you installed with**:

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

  ```bash Homebrew theme={null}
  brew update && brew upgrade mel
  ```
</CodeGroup>

<Note>
  On Homebrew, always run `brew update` first — it refreshes the tap so Homebrew sees the newest formula. A bare `brew upgrade mel` can report "already installed" because your local copy of the tap is stale.
</Note>

`mel` also nudges you when a newer version is published: after a command finishes, a one-line notice prints to `stderr` (never in JSON output, and never for agents or piped/non-interactive output). Silence it with `MEL_NO_UPDATE_NOTIFIER=1`. Releases follow [semantic versioning](https://semver.org) — a major bump (for example `1.x` → `2.x`) can include breaking changes, so review what changed before upgrading across one.

## Get an API key

`mel` authenticates with a Melius API key. Create one in the Melius app under **Team settings → Integrations** — give it a name, then copy it when it's shown (you only see it once).

See [API authentication](/api/authentication) for how keys are scoped.

<Warning>
  Treat an API key like a password. Don't commit it to source control or paste it into client-side code. Set it from an environment variable or a secrets manager.
</Warning>

## Authenticate

There are two ways to give `mel` your key — pick one.

<Tabs>
  <Tab title="Interactive (log in once)">
    Store the key in `~/.mel/config.json` so every command picks it up automatically:

    ```bash theme={null}
    mel auth login --api-key mel_...
    ```

    Confirm it worked:

    ```bash theme={null}
    mel auth whoami
    ```

    This returns your user (id, name, email). Clear stored credentials any time with `mel auth logout`.
  </Tab>

  <Tab title="Environment variables (CI & agents)">
    For CI, containers, or an agent sandbox, set env vars instead — nothing is written to disk:

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

    Every command reads `MEL_API_KEY` on each run. This is the recommended setup for [driving `mel` from an agent](/cli/agents).
  </Tab>
</Tabs>

## Configuration

`mel` resolves settings in this order — **environment variables → config file → defaults**:

| Setting  | Env var        | Config key | Default                  |
| -------- | -------------- | ---------- | ------------------------ |
| API key  | `MEL_API_KEY`  | `apiKey`   | —                        |
| Base URL | `MEL_BASE_URL` | `baseUrl`  | `https://api.melius.com` |
| Team     | `MEL_TEAM_ID`  | `teamId`   | the key's team           |

Inspect or change the config file:

```bash theme={null}
mel config get           # show all config
mel config set teamId <teamId>
mel config path          # → ~/.mel/config.json
```

## Choosing a team

An API key acts as the user who created it, and can act on **any team that user is a member of**. Requests default to the team the key was created in; to act on another, set a team id:

```bash theme={null}
mel team list                # teams your key can act on
mel team switch <teamId>     # or export MEL_TEAM_ID=<teamId>
```

Your permissions are scoped **per team, exactly like the app** — a key never grants more than your own role in the team you're acting on. If you're an owner in the team where you made the key but only an editor in another, switching to that team lets you create and edit content there, but **not** owner/admin-only actions (managing members, billing, or team settings); a viewer can only read. Switching teams never escalates what you can do.

## Shell completion

`mel` generates tab-completion scripts for bash, zsh, and fish. They're built from the live command tree, so they never drift from the commands you have installed.

<CodeGroup>
  ```bash bash theme={null}
  echo 'eval "$(mel completion bash)"' >> ~/.bashrc
  ```

  ```bash zsh theme={null}
  echo 'eval "$(mel completion zsh)"' >> ~/.zshrc
  ```

  ```bash fish theme={null}
  mel completion fish > ~/.config/fish/completions/mel.fish
  ```
</CodeGroup>

Open a new shell (or re-source your rc file), then press Tab after `mel` to complete command groups and their subcommands.

## Next steps

<Columns cols={2}>
  <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, and exit code.
  </Card>
</Columns>