# Configuration

> Where the CLI keeps its config file and what is in it, profiles, the config keys, the base URL and every environment variable it reads.

Source: https://machinemail.dev/docs/cli/configuration

The CLI needs two things to call the API: a key and a base URL. Both come from flags, environment variables or a profile in the config file, in that order. Everything else has a default, so most people never edit the config file by hand.

## Config file

```bash title="Terminal"
machinemail config path
```

| Platform        | Default path                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------- |
| macOS and Linux | `~/.config/machinemail/config.json`, or `$XDG_CONFIG_HOME/machinemail/config.json` when that is set |
| Windows         | `%USERPROFILE%\.config\machinemail\config.json`                                                     |

`MACHINEMAIL_CLI_CONFIG` points at another file, which is handy for tests and for keeping a project's profiles next to it. The CLI creates the file on first `login`, with mode `0600` inside a `0700` directory, and rewrites it atomically.

```json title="~/.config/machinemail/config.json"
{
  "current_profile": "default",
  "settings": { "update_check": false },
  "profiles": {
    "default": {
      "api_key": "mm_live_...",
      "base_url": "https://api.machinemail.dev"
    },
    "agent": {
      "api_key": "...",
      "base_url": "https://api.machinemail.dev",
      "inbox": "agent-ygsa50y7nfzo@machinemail.dev",
      "agent": { "registration_id": "reg_...", "identity_assertion": "...", "claim_token": "..." }
    }
  }
}
```

A profile made by `machinemail register` also holds its default `inbox` and an `agent` block: the credentials that renew its short-lived token. Leave that block to the CLI.

`machinemail config list` prints the file with keys masked and agent credentials as `(set)`:

```text
current_profile=default
profiles.agent.base_url=https://api.machinemail.dev
profiles.agent.inbox=agent-ygsa50y7nfzo@machinemail.dev
profiles.agent.agent.registration_id=reg_01m4gngsfh00008vwn3sjg847x
profiles.agent.agent.identity_assertion=(set)
profiles.agent.agent.claim_token=(set)
profiles.agent.api_key=…E5VQ
profiles.default.api_key=mm_live_…hdYv
profiles.default.base_url=https://api.machinemail.dev
```

## Config keys

Read and change them with `config get`, `config set` and `config unset` rather than editing the file:

| Key               | Scope       | Meaning                                                                                                                        |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `base_url`        | per profile | API origin. Default `https://api.machinemail.dev`.                                                                             |
| `api_key`         | per profile | The API key, always printed masked. `config set api_key -` reads it from stdin; `login` is better, as it checks the key first. |
| `current_profile` | global      | The profile used when neither `--profile` nor `MACHINEMAIL_PROFILE` is set. Same as `profiles use`.                            |
| `update_check`    | global      | Opt in to a daily update check. Off by default.                                                                                |

```bash title="Terminal"
machinemail config set current_profile work
machinemail config get base_url --json
```

```json
{
  "key": "base_url",
  "value": "https://api.machinemail.dev",
  "source": "default",
  "profile": "default"
}
```

`config get` prints the value the CLI will actually use, after flags and environment variables, and with `--json` says where it came from (`flag`, `env`, `profile` or `default`). Per-profile keys go to the current profile, or the one named with `--profile`, which `config set` creates if needed.

## Profiles

A profile is a named set of `api_key`, `base_url` and, for registered agents, `inbox`. The profile in use is the first of:

1. `--profile <name>`
2. `MACHINEMAIL_PROFILE`
3. `current_profile` in the config file
4. `default`

```bash title="Terminal"
machinemail profiles list          # * marks the current one
machinemail profiles use work      # also: profiles switch
machinemail profiles delete old    # also: profiles rm; asks you to type the name
```

`login`, `register` and `config set` create profiles. See [Authentication](/content/docs/cli/authentication#profiles/index.html) for working with several keys.

## Base URL

The CLI talks to `https://api.machinemail.dev`. The base URL in use is the first of `--base-url`, `MACHINEMAIL_BASE_URL`, the profile's `base_url`, and that default; you normally never set it. `machinemail config get base_url --json` shows the value in use and where it came from. `doctor` warns about a plain `http://` URL to a remote host, since the key would cross the network unencrypted.

`machinemail open` and the `login` link go to the dashboard at `machinemail.dev`. `MACHINEMAIL_DASHBOARD_URL` overrides it.

## Environment variables

| Variable                    | Effect                                                                        |
| --------------------------- | ----------------------------------------------------------------------------- |
| `MACHINEMAIL_API_KEY`       | The API key. Overrides the profile's key; `--api-key` overrides it.           |
| `MACHINEMAIL_PROFILE`       | The profile to use. `--profile` overrides it.                                 |
| `MACHINEMAIL_BASE_URL`      | The API origin. Overrides the profile's; `--base-url` overrides it.           |
| `MACHINEMAIL_INBOX`         | Default inbox for `send --from`, `wait --inbox` and `read`.                   |
| `MACHINEMAIL_CLI_CONFIG`    | Path of the config file.                                                      |
| `XDG_CONFIG_HOME`           | Base directory of the default config path.                                    |
| `XDG_CACHE_HOME`            | Where the update check caches its result (`machinemail/update-check.json`).   |
| `MACHINEMAIL_MAX_RETRIES`   | Retries for rate-limited and failed requests (default 3; `0` turns them off). |
| `MACHINEMAIL_DASHBOARD_URL` | Dashboard origin for `open` and sign-in links.                                |
| `MACHINEMAIL_UPDATE_CHECK`  | `1` or `0`: turn the update check on or off, whatever the config says.        |
| `NO_UPDATE_NOTIFIER`        | Turns the update check off. `CI` does too.                                    |
| `NO_COLOR`                  | Any value turns color off. So does `TERM=dumb`.                               |
| `CI`                        | No spinners, no prompts (deletes need `--yes`), no update check.              |
| `BROWSER`                   | The program `open` and `login` use to open a URL.                             |
| `COLUMNS`                   | Output width when the terminal does not report one.                           |

## Updates

The update check is off by default. With `update_check` on (or `MACHINEMAIL_UPDATE_CHECK=1`), the CLI fetches the latest release's version at most once a day and prints one muted line on stderr after an interactive command when a newer one exists. It never runs in CI or for piped output. It reads the latest release's `manifest.json` from github.com/machinemail/cli; `MACHINEMAIL_UPDATE_URL` points it elsewhere (and is needed on 0.1.0, which was built before that address was set).