# CLI

Every command group in the OpenEmail CLI, the global flags available on all of them, and the output conventions for scripting.

Every command group in the OpenEmail CLI. The authoritative source is always the
binary itself.

Run `openemail <command> --help` for the full flag list of any group, and
`openemail version` to confirm what you are running.

## Command groups

| Command | What it does |
| --- | --- |
| `accounts` | Manage tenant accounts (system callers only for create/list) |
| `admin` | Operator-only maintenance (system credentials required) |
| `api` | Call any core API route directly (escape hatch) |
| `completion` | Generate the shell autocompletion script |
| `credentials` | Manage a mailbox's IMAP/SMTP credentials |
| `deliver` | MTA-facing delivery: RCPT pre-flight check and test inbound injection |
| `domains` | Manage domains |
| `keys` | Manage API keys |
| `labels` | Manage a mailbox's labels (IMAP folders) |
| `login` | Authenticate and store an API key for this profile |
| `logout` | Revoke this profile's key and remove stored credentials |
| `mailboxes` | Manage mailboxes |
| `messages` | List, read, append, flag, label, and delete a mailbox's messages |
| `patterns` | Manage pattern routes (local-part globs) |
| `pickups` | Manage a mailbox's POP3 pickup sources |
| `routes` | Manage address routes |
| `search` | Full-text search a mailbox's messages |
| `send` | Submit an outbound message |
| `sieve` | Manage a mailbox's Sieve filter scripts (ManageSieve) |
| `status` | Check core reachability and authentication |
| `threads` | List and read conversation threads |
| `ui` | Browse the platform in an interactive console |
| `upgrade` | Explain how to upgrade (openemail does not self-update) |
| `version` | Print the CLI version |
| `watch` | Tail a mailbox's live change events over WebSocket |
| `whoami` | Show the identity the current key resolves to |

## Profiles

A **profile** is a named CLI configuration with its own API URL, account, and
default mailbox. Use profiles to keep production and staging apart, and
`--profile` to pick one for a single command.

## Interactive console

```bash
openemail ui
```

`ui` opens a full-screen terminal client rather than printing and exiting. It
uses the current profile's credentials, so sign in first. See the
[Quickstart](/docs/quickstart).

It is the fastest way to look around: browse mailboxes, read threads and
messages, and inspect routes, patterns, and domains. It is also a working
client, so you can create mailboxes and send and receive mail from inside it.

Reach for it when you are exploring or doing one-off work by hand, and for the
individual commands when you are scripting. The console paints a screen instead
of emitting text, so unlike every other command here it cannot be piped into
another program.

## Global flags

Available on every command.

| Flag | What it does |
| --- | --- |
| `--api-key` | Use this bearer token for one invocation (env: `OPENEMAIL_API_KEY`) |
| `--api-url` | Override the API base URL (env: `OPENEMAIL_API_URL`) |
| `--debug` | Print debug detail on errors |
| `--json` | Output machine-readable JSON |
| `--no-color` | Disable color output |
| `--no-keyring` | Store keys in a 0600 file instead of the OS keychain (env: `OPENEMAIL_NO_KEYRING`) |
| `--profile` | Config profile to use (env: `OPENEMAIL_PROFILE`) |
| `-v`, `--version` | Print the CLI version |

## Output and scripting

Data goes to stdout so it can be piped. Messages and warnings go to stderr, so
they stay visible even when stdout is being consumed by another program.

`--json` is the bridge between the CLI and the API: the payload it prints is the
payload the API returns.

Exit codes: `0` success, `1` error, `2` usage problem, `4` authentication
failure.

## Defaults worth knowing

`openemail mailboxes use <mailboxId|address>` sets the default mailbox for the
current profile. Message, label, and Sieve commands use it, which is why they
work without `-m` once it is set.

> Skipping the default mailbox is the most common reason
> `openemail messages list` fails on a fresh install.