configuration.md

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

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.

{
  "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. 
machinemail config set current_profile work
machinemail config get base_url --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
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 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).