--- title: "Sign-in and setup" description: "MachineMail CLI commands to sign in and out, show and check the credential in use with whoami and doctor, and register or claim an agent without a human." canonical: "https://machinemail.dev/docs/cli/commands/setup" --- # Sign-in and setup > MachineMail CLI commands to sign in and out, show and check the credential in use with whoami and doctor, and register or claim an agent without a human. Source: https://machinemail.dev/docs/cli/commands/setup Commands that sign the CLI in and out, show and check the credential in use, and register an agent without a human. | Command | Summary | | ----------------------- | ------------------------------------------------------------------------------- | | [`login`](#login) | Sign in with the browser (or an API key) and save the key to a profile | | [`whoami`](#whoami) | Show the key, profile and API in use, and check the key | | [`doctor`](#doctor) | Check the config, connectivity, key, clock and CLI version | | [`register`](#register) | Register this agent (auth.md): a sandbox inbox and credentials, no human needed | | [`claim`](#claim) | Get a new claim code for a registered agent, and wait for a human to claim it | | [`logout`](#logout) | Remove the stored key from a profile, and optionally revoke it | Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags). ## 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 \" (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 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 ` | `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 login machinemail login --no-browser printf %s "$MACHINEMAIL_API_KEY" | machinemail login --key - machinemail login --profile work printf %s "$WORK_API_KEY" | machinemail login --profile work --key - ``` ## 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 whoami ``` #### Examples ```bash machinemail whoami machinemail whoami --profile work machinemail whoami --json | jq -r '.organization_id' ``` ## doctor Check the config, connectivity, key, clock and CLI version. Runs every check and reports each one: the config file and its permissions, the profile and API URL in use, whether a key is set, whether the API answers (GET /health and /health/ready), whether it accepts the key (GET /v0/auth/me), clock skew against the API, and the CLI version. Exits with the first failure (7 config, 6 network, 3 auth, 1 other), or 0. No key is ever printed unmasked, even with --verbose. ```bash machinemail doctor [flags] ``` #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--offline` | `boolean` | | Skip the checks that call the API. | #### Examples ```bash machinemail doctor machinemail doctor --profile work --verbose machinemail doctor --json | jq '.checks[] | select(.status != "ok")' ``` ## register Register this agent (auth.md): a sandbox inbox and credentials, no human needed. Anonymous auth.md registration: creates a sandbox organization with one inbox on the shared domain, gets an access token and saves everything in a profile (renewed automatically). The sandbox reaches only its own inbox, can send 10 messages to 10 different recipients per 24 hours, with at most 5 recipients per message, and expires after 24 hours unless a human claims it. The command starts a claim and prints a link and a 6-digit code for a human; --wait blocks until they finish, then switches to the post-claim credentials. Uses the current profile when it has no key, else a profile named "agent" (or --profile). ```bash machinemail register [flags] ``` #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--name ` | `string` | | Agent name shown to the human at claim time. | | `--email ` | `string` | | Only this person can claim the agent. | | `--claim` | `boolean` | | Start a claim now (default; --no-claim to skip and run machinemail claim later). | | `--wait` | `boolean` | | Wait until a human claims the agent. | | `--force` | `boolean` | | Replace a profile that holds an API key. | #### Examples ```bash machinemail register --name "Research agent" machinemail register --email ada@acme.dev --wait machinemail register --json | jq -r .inbox_id ``` ## claim Get a new claim code for a registered agent, and wait for a human to claim it. For a profile made by `machinemail register`: starts a claim (a link and a 6-digit code for a human, valid 10 minutes; earlier codes stop working) and, with --wait, blocks until the human finishes, then saves the post-claim credentials. ```bash machinemail claim [flags] ``` #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--email ` | `string` | | Only this person can claim the agent. | | `--wait` | `boolean` | | Wait until a human claims the agent. | #### Examples ```bash machinemail claim machinemail claim --email ada@acme.dev --wait ``` ## 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 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 logout machinemail logout --yes machinemail logout --no-revoke --profile work ```