Configuration · MachineMail Docs

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):

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.

Terminal

machinemail config set base_url http://127.0.0.1:8080 --profile local
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:

--profile <name>
MACHINEMAIL_PROFILE
current_profile in the config file
default

Terminal

machinemail profiles list          # * marks the current one
machinemail profiles use staging   # 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 for working with several keys.

Base URL

The CLI talks to https://api.machinemail.dev unless told otherwise. The base URL in use is the first of --base-url, MACHINEMAIL_BASE_URL, the profile’s base_url, and the default. Point a profile at another instance once and keep using it:

Terminal

machinemail login --profile local --base-url http://127.0.0.1:8080
machinemail inboxes list --profile local

A key belongs to one API, so a profile keeps its key and base URL together. doctor warns about plain http:// to a host other than your own machine, since the key would cross the network unencrypted.

machinemail open and the login link go to the dashboard for the API in use: machinemail.dev for api.machinemail.dev, and the API’s own origin for a local or self-hosted instance. 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. Until releases are public there is nothing to check against, and it makes no network call.