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
openemail uiui 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.
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 listfails on a fresh install.