---
title: "auth"
description: "Sign in with an API key and inspect the credential. The `machinemail auth` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/auth"
---

# auth

> Sign in with an API key and inspect the credential. The `machinemail auth` commands: arguments, flags, examples and the API routes they call.

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

Sign in with an API key and inspect the credential.

| Command                       | Summary                                                                  |
| ----------------------------- | ------------------------------------------------------------------------ |
| [`auth login`](#auth-login)   | Sign in with the browser (or an API key) and save the key to a profile   |
| [`auth logout`](#auth-logout) | Remove the stored key from a profile, and optionally revoke it           |
| [`auth me`](#auth-me)         | The credential as the API reports it (GET /v0/auth/me; whoami says more) |
| [`auth status`](#auth-status) | Show the key, profile and API in use, and check the key                  |
| [`auth whoami`](#auth-whoami) | Show the key, profile and API in use, and check the key                  |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## auth login

Sign in with the browser (or an API key) and save the key to a profile.

Signs in with the browser: prints a code and a link (Enter opens it), you approve the code in the dashboard while signed in, and the API creates an API key named "CLI on \<hostname>" (every permission except inbound\_raw) that is saved to a profile in the config file (mode 0600). Without a terminal or a browser it prints the link and waits. For CI and scripts, give an existing key instead: --key - (stdin), --api-key -, or MACHINEMAIL\_API\_KEY; --paste asks for one with a hidden prompt. Given keys are checked against GET /v0/auth/me unless --no-verify. --profile keeps several keys side by side, for example one per organization. Agents without a human can start with `machinemail register`.

```bash
machinemail auth login [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--browser` | `boolean` |  | Offer to open the browser for sign-in (default; --no-browser only prints the URL). |
| `--paste` | `boolean` |  | Paste an existing API key into a hidden prompt instead of signing in with the browser. |
| `--key <key|->` | `string` |  | The API key, or - to read it from stdin (keeps it out of shell history). |
| `--with-key` | `boolean` |  | Read the key from stdin (same as --key -). |
| `--no-verify` | `boolean` |  | Save the key without checking it against the API (offline setup). |

#### Examples

```bash
machinemail auth login
machinemail auth login --no-browser
printf %s "$MACHINEMAIL_API_KEY" | machinemail auth login --key -
machinemail auth login --profile work
printf %s "$WORK_API_KEY" | machinemail auth login --profile work --key -
```

## auth logout

Remove the stored key from a profile, and optionally revoke it.

Deletes the stored key from the profile (the profile and its base URL stay), and for a registered agent the credentials that renew it. On a terminal it offers to revoke the key on the server first (DELETE /v0/api-keys/\{id}); --revoke (or --yes) revokes without asking, --no-revoke keeps the key valid. Without a terminal the key is only removed locally unless --revoke or --yes is given.

```bash
machinemail auth logout [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--revoke` | `boolean` |  | Revoke the key on the server too (--no-revoke: only remove it here). Asks on a terminal. |

#### Examples

```bash
machinemail auth logout
```

## auth me

The credential as the API reports it (GET /v0/auth/me; whoami says more).

The identity and scope of the credential: which organization, pod and inbox it is bound to. Useful with a pod or inbox key to discover its scope.

```bash
machinemail auth me [flags]
```

#### Examples

```bash
machinemail auth me
```

#### API

- [`GET /v0/auth/me`](https://machinemail.dev/docs/reference/api/auth)

## auth status

Show the key, profile and API in use, and check the key.

Shows the profile, API and key the CLI will use and where each came from (flag, env, profile or default), then checks the key with GET /v0/auth/me. Exits 3 when there is no key or the API rejects it.

```bash
machinemail auth status
```

#### Examples

```bash
machinemail auth status
```

## auth whoami

Show the key, profile and API in use, and check the key.

Shows the profile, API and key the CLI will use and where each came from (flag, env, profile or default), then checks the key with GET /v0/auth/me. Exits 3 when there is no key or the API rejects it.

```bash
machinemail auth whoami
```

#### Examples

```bash
machinemail auth whoami
```