CLI reference
Work with email and manage the Fluxmail server from the command line.
The Fluxmail CLI reads and manages email through a selected local or remote instance. It also starts MCP and REST servers and handles instance administration. Run fluxmail setup for a new local instance, or use fluxmail login to add an existing instance. See Authentication and instances for profiles, sessions, and remote URL rules.
See Use the CLI for email, setup, and administration workflows. This page is the complete command reference.
Install the CLI
Install Fluxmail globally:
npm install -g fluxmailTo run a command without a global installation, replace fluxmail with npx -y fluxmail@latest. Pin an exact version instead of @latest to stay on one release.
If Fluxmail runs under Docker, prefix each command with docker compose exec fluxmail. For example:
docker compose exec fluxmail fluxmail accounts listCommand reference
| Command | Description |
|---|---|
fluxmail setup | Create the first local administrator or claim a migrated administrator |
fluxmail login | Log in to a local or remote instance |
fluxmail logout | Revoke the current CLI session |
fluxmail instances | Manage local and remote CLI instances |
fluxmail instances list | List configured instances |
fluxmail instances use | Select the default instance |
fluxmail instances remove | Remove a CLI profile and its local session |
fluxmail auth | Manage interactive authentication |
fluxmail auth recover-admin | Reset an administrator password using local filesystem access |
fluxmail auth sessions | List sessions for the current member |
fluxmail auth revoke-session | Revoke one of the current member's sessions |
fluxmail serve | Run the HTTP server (MCP at /mcp and REST at /api/v1) |
fluxmail stdio | Run as a stdio MCP server (for Claude Desktop / Claude Code local config) |
fluxmail accounts | Manage connected email accounts |
fluxmail accounts add | Connect a Gmail, Outlook, or IMAP account |
fluxmail accounts configure | Set special folder paths for an IMAP account |
fluxmail accounts list | List connected accounts |
fluxmail accounts remove | Disconnect an account and delete its stored tokens |
fluxmail accounts assign | Change mailbox ownership |
fluxmail accounts access | Set who can access a mailbox |
fluxmail members | Manage members (people using this instance) |
fluxmail members add | Add a member (subject to the plan seat limit) |
fluxmail members list | List members with their mailbox and API key counts |
fluxmail members remove | Remove a member after reassigning or removing their mailboxes |
fluxmail members role | Change a member role |
fluxmail members status | Activate or suspend a member |
fluxmail members invite | Issue a new enrollment code |
fluxmail members password-reset | Issue a password reset code |
fluxmail members sessions | List sessions for a member |
fluxmail members revoke-session | Revoke a member session |
fluxmail apikey | Manage API keys for the HTTP MCP and REST APIs |
fluxmail apikey capabilities | List capabilities for API key permission policies |
fluxmail apikey create | Create an API key (shown once) |
fluxmail apikey list | List API keys |
fluxmail apikey accounts | Replace or clear an API key mailbox allowlist |
fluxmail apikey permissions | Change the permissions for an API key |
fluxmail apikey revoke | Revoke an API key |
fluxmail license | Manage the paid-tier license |
fluxmail license activate | Store a license key and validate it with the license server |
fluxmail license status | Show the configured license and cached lease |
fluxmail license deactivate | Release the license from this instance and remove the stored key and cached lease |
fluxmail config | Inspect and initialize deployment configuration |
fluxmail config init | Create config.toml in the Fluxmail data directory |
fluxmail config show | Show effective configuration, sources, paths, and restart requirements |
fluxmail config migrate | Import settings from an env file without deleting it |
fluxmail oauth | Manage OAuth applications |
fluxmail oauth status | Show OAuth application status without secrets |
fluxmail oauth configure | Configure an OAuth application |
fluxmail oauth configure google | Configure a custom Google OAuth application |
fluxmail oauth configure outlook | Configure a custom Microsoft OAuth application |
fluxmail oauth reset | Remove a stored OAuth application |
fluxmail logs | Show recent local log entries |
fluxmail telemetry | Manage anonymous usage telemetry |
fluxmail telemetry disable | Stop sending anonymous usage telemetry |
fluxmail telemetry enable | Allow anonymous usage telemetry |
fluxmail telemetry status | Show whether anonymous usage telemetry is enabled |
fluxmail folders | Work with navigable mailbox folders |
fluxmail folders list | List folders in an email account |
fluxmail labels | Work with Gmail labels and Outlook categories |
fluxmail labels list | List Gmail user labels or Outlook categories |
fluxmail emails | Read, send, and organize email |
fluxmail emails list | List and filter messages |
fluxmail emails search | Search messages |
fluxmail emails get | Get a complete message |
fluxmail emails send | Send or schedule a message |
fluxmail emails forward | Forward a message |
fluxmail emails modify | Apply one action to one or more messages |
fluxmail threads | Read email threads |
fluxmail threads get | Get a complete thread |
fluxmail drafts | Create and manage drafts |
fluxmail drafts create | Create a draft |
fluxmail drafts update | Replace the content of a draft |
fluxmail drafts delete | Delete a draft |
fluxmail scheduled | Manage scheduled sends |
fluxmail scheduled list | List scheduled sends |
fluxmail scheduled cancel | Cancel a scheduled send and keep its draft |
fluxmail attachments | Download message attachments |
fluxmail attachments download | Download an attachment |
fluxmail status | Show mailbox and provider status for the selected instance |
Add --help to a command to view its usage in the terminal. For example, run fluxmail accounts add --help.
Gmail and Outlook connections
Fluxmail uses the hosted browser flow when FLUXMAIL_PUBLIC_URL is a non-loopback address. Otherwise, it uses the local loopback flow. Hosted links expire after 10 minutes and work once.
The --hosted and --local options override the automatic choice. You cannot combine them or use them with an IMAP account. The provider name microsoft is an alias for outlook.
IMAP account options
fluxmail accounts add imap accepts separate settings for incoming and outgoing mail. Without a password environment variable, Fluxmail prompts for the password in an interactive terminal.
See Connect IMAP/SMTP for a complete setup example and help with folder detection.
MCP permission options
The named profiles are read-only, read-write, and full. Use repeated --allow options to build a custom policy. You cannot combine --profile and --allow on the same command.
Permissions passed to fluxmail stdio apply to that process. HTTP permissions are stored with the API key and can be changed with fluxmail apikey permissions. See Permissions for the capability list and workflow requirements.
Last updated