@fredlackey/cli-mailu

Command-line interface for the Mailu email server. Manage domains, user mailboxes, aliases, and (over IMAP) archived mail from the terminal. JSON output by default so AI agents and scripts can consume it directly, with a human-friendly mode when you're working interactively.

Install

npm install -g @fredlackey/cli-mailu

Usage

Every command accepts credentials directly as flags. No setup step is required.

mailu domain list \
  --base-url https://mail.example.com \
  --api-key <key>

mailu user create \
  --base-url https://mail.example.com \
  --api-key <key> \
  --email [email protected] \
  --password <password> \
  --name "Hello World"

IMAP-based archive commands also accept their credentials inline:

mailu archive fetch \
  --base-url https://mail.example.com \
  --api-key <key> \
  --imap-host mail.example.com \
  --imap-port 993 \
  --imap-user [email protected] \
  --imap-password <password> \
  --email [email protected] \
  --data-dir ./backup

If you've already run mailu configure, you can omit the credential flags:

mailu domain list
mailu alias create \
  --email [email protected] \
  --destination [email protected]
mailu domain dns --name example.com
mailu archive fetch \
  --email [email protected] \
  --data-dir ./backup

Configure (Optional)

The configure command is optional. Every command accepts credentials directly as flags (e.g. --api-key, --base-url). You never need to run configure to use this tool. It exists as a convenience so you don't have to pass the same flags on every invocation.

mailu configure \
  --base-url https://mail.example.com \
  --api-key <key>

Running mailu configure without flags prompts for each value interactively. Credentials are stored in ~/.config/cli-mailu/config.json and that file is the only config source. There are no environment variables to set.

To use the IMAP-based archive commands, add IMAP credentials in the same configure step or a separate one:

mailu configure \
  --imap-host mail.example.com \
  --imap-port 993 \
  --imap-user [email protected] \
  --imap-password <password>

If a required credential is missing at runtime, the error tells you exactly what to do:

{
  "error": "Missing required value: --api-key. Pass it as a flag or run \"mailu configure\"."
}

Full Command Reference

For the complete list of commands and flags, see COMMANDS.md.

Output

All commands write JSON to stdout by default. When run in an interactive terminal, output switches to a human-friendly format with colors. Use the global --json and --interactive flags to override the auto-detection.

Contributing

If you find a gap or have a feature request, open an issue or submit a pull request on GitHub.

Questions?

If you have questions, comments, or just want to talk shop, feel free to reach out.

Fred Lackey
[email protected]
https://fredlackey.com

License

Apache-2.0