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

<Callout>The CLI is in early access. Releases are published on [github.com/machinemail/cli](https://github.com/machinemail/cli/releases).</Callout>

## Install

```bash title="Terminal"
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](/content/docs/cli/installation/index.html).

```bash title="Terminal"
machinemail --version
```

```text
machinemail 0.1.0 (877499ccae83, linux-x64)
```

## Sign in

```bash title="Terminal"
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](/content/docs/cli/authentication/index.html).

Check what you are signed in as:

```bash title="Terminal"
machinemail whoami
```

```text
✓ 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:

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

Send an email from it:

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

```text
✓ 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:

```bash title="Terminal"
CODE=$(machinemail wait --inbox "$INBOX" --otp --timeout 5m)
```

List and read messages:

```bash title="Terminal"
machinemail messages list "$INBOX"
machinemail read msg_01m4gnfsw200001e83690x4dm8
```

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

```bash title="Terminal"
machinemail tail --inbox "$INBOX"
```

Every other endpoint is a `machinemail <resource> <action>` command, generated from the [API reference](/content/docs/reference/api/index.html). `--help` works at every level:

```bash title="Terminal"
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

- [Installation](/content/docs/cli/installation/index.html): Binaries per platform and shell completions.
- [Authentication](/content/docs/cli/authentication/index.html): Browser sign-in, API keys for CI, profiles, logout and where the key is stored.
- [Output and scripting](/content/docs/cli/output-and-scripting/index.html): JSON and NDJSON output, `--fields`, exit codes, and using the CLI from scripts and agents.
- [Agent workflows](/content/docs/cli/agent-workflows/index.html): Sign-ups with `wait --otp`, reading mail safely, and anonymous registration for agents.
- [Configuration](/content/docs/cli/configuration/index.html): The config file, profiles, environment variables and the API base URL.
- [Command reference](/content/docs/cli/commands/index.html): Every command with its arguments, flags, examples and API route.