# The CLI

`mdbrain` is markdownbrain.ai's command-line client. Three of its commands are the API from a shell.

## Installing

On macOS and Linux:

```sh
curl -fsSL https://markdownbrain.ai/install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://markdownbrain.ai/install.ps1 | iex
```

## Credentials

`mdbrain` uses `MDBRAIN_API_KEY` when it is set. Without one, it uses the session `mdbrain login` keeps. `MDBRAIN_API_URL` points it at another API address; your login is only ever sent to markdownbrain.ai's own address or to your own machine, so any other address needs a key.

## The commands

- `mdbrain call <operation> [--argument value]...` runs any operation and prints its JSON answer. An argument is written `--workspace-id` or `--workspace_id`. A value written `@path` is read from that file, and `--json <file>` reads every argument from a JSON file, or `-` for standard input. `mdbrain call --list` lists every operation with its method and route.
- `mdbrain read <workspace> <path>` prints a document's content as it is, for redirecting into a file.
- `mdbrain upload <workspace> <local-file>` uploads an image of any size, with `--to <folder>` and `--name <name>` when you want them.

Standard output carries the answer's body and nothing else, refusals included, so a script can always parse it. Everything meant for a person goes to standard error.

## Exit codes

| Exit code | Meaning |
|---|---|
| `0` | ok: the operation succeeded |
| `1` | refused: the server said no |
| `2` | usage: the command was wrong before anything was sent |
| `3` | auth: the credential is missing or refused |
| `4` | limited: the rate limit was reached |
| `5` | transport: no usable answer came back, or the server failed |