## Config file

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

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.

~/.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)`:

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

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`

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.

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