cli.md

title: "CLI" description: "The machinemail command line tool - what it covers, how to install it and sign in, and the first commands to run, from a terminal or a script." canonical: "https://machinemail.dev/docs/cli"

CLI

The machinemail command line tool - what it covers, how to install it and sign in, and the first commands to run, from a terminal or a script.

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

machinemail (also installed as mm) is the MachineMail API from the terminal. It has a command for every /v0 endpoint, plus a few built for agents and shell scripts: create an inbox and print its address, send in one line, wait for a verification code, read a message with its trust verdict, and follow new mail as it arrives. It is a single binary with no runtime to install.

On a terminal it prints tables and detail panes. When its output is piped, or with --json, it prints JSON instead, so agents and scripts use the same commands people do.

The CLI is in early access. Releases are published on github.com/machinemail/cli.

Install

curl -fsSL https://machinemail.dev/install.sh | sh

The script installs machinemail and mm into ~/.local/bin for macOS or Linux on x64 or arm64. Windows, pinned versions and completions are on Installation.

machinemail --version

machinemail 0.1.0 (877499ccae83, linux-x64)

Sign in

machinemail login

The CLI prints an 8-letter code and a link to machinemail.dev/cli. Approve the code in the dashboard and the CLI receives an API key named CLI on <your hostname>, saved in ~/.config/machinemail/config.json. In CI, set MACHINEMAIL_API_KEY instead. Both are covered in Authentication.

Check what you are signed in as:

machinemail whoami

✓ Signed in with an organization key for Acme
PROFILE       default (profile)
API           https://api.machinemail.dev (default)
KEY           mm_live_…hdYv (profile)
ORGANIZATION  Acme (org_01m4gnem700000j9kk6vas9c0c)
SCOPE         organization
KEY ID        key_01m4gnem710001snxpesc1xhpr

First commands

Create an inbox. Piped, inbox new prints only the address:

INBOX=$(machinemail inbox new --username support-agent --display-name "Support agent")
echo "$INBOX"   # support-agent@machinemail.dev

Send an email from it:

machinemail send --from "$INBOX" --to ada@example.com -s "Hello" --text "Hi Ada, this came from the CLI."

✓ Sent to ada@example.com
  message  msg_01m4gnf4b80000zyh5cesdhpac
  thread   thd_01m4gnf4b800012grmwz1agfmj
  from     support-agent@machinemail.dev

Use the inbox to sign up for a service, then wait for the verification code and keep it:

CODE=$(machinemail wait --inbox "$INBOX" --otp --timeout 5m)

List and read messages:

machinemail messages list "$INBOX"
machinemail read msg_01m4gnfsw200001e83690x4dm8

Follow new mail as it arrives (Ctrl-C to stop):

machinemail tail --inbox "$INBOX"

Every other endpoint is a machinemail <resource> <action> command, generated from the API reference. --help works at every level:

machinemail --help                    # commands, grouped
machinemail webhooks --help           # the actions of one resource
machinemail webhooks create --help    # arguments, flags, examples and the endpoint it calls

Next