InboxFerry
CLI Reference
Headless IMAP backup and migration from the command line.
inboxferry-cli is the headless companion to the InboxFerry desktop app. It reads the same configuration and credentials, so accounts you set up in the GUI are immediately available in scripts and scheduled jobs.
Installation
The binary lives inside the app bundle. Create a symlink for convenient access:
# macOS
ln -s /Applications/InboxFerry.app/Contents/MacOS/inboxferry-cli /usr/local/bin/inboxferry-cli
# Windows — add the install directory to PATH, or call it directly:
# "C:\Program Files\InboxFerry\inboxferry-cli.exe"
Getting started
List your configured accounts:
inboxferry-cli accounts list
Back up an account:
inboxferry-cli backup work-gmail ~/Mail/backup/work-gmail
Preview without writing (dry run):
inboxferry-cli backup work-gmail ~/Mail/backup/work-gmail --dry-run
Migrate one IMAP account into another:
inboxferry-cli migrate imap old-gmail new-fastmail
Restore a backup into an account:
inboxferry-cli restore ~/Mail/backup/work-gmail new-account
Global options
These options must appear before the subcommand.
inboxferry-cli [GLOBAL OPTIONS] SUBCOMMAND [SUBCOMMAND OPTIONS]
| Option | Description |
|---|---|
-h, --help | Print help and exit |
--help-all | Print help for all subcommands and exit |
--version | Print version and exit |
--config-dir PATH | Use a custom InboxFerry data directory instead of the default |
-q, --quiet | Suppress progress output; errors still go to stderr |
The default config directory is the same one the desktop app uses:
- macOS:
~/Library/Application Support/InboxFerry - Windows:
%APPDATA%\InboxFerry - Linux:
~/.config/InboxFerry
accounts
Manage configured IMAP accounts.
accounts list
inboxferry-cli accounts list
Prints all accounts stored in the current configuration, one per line, showing the account ID and display name.
backup
Back up an IMAP account to a local directory of mbox files.
inboxferry-cli backup ACCOUNT-ID DEST-PATH [OPTIONS]
| Argument / Option | Description |
|---|---|
ACCOUNT-ID | Account ID from accounts list |
DEST-PATH | Destination directory; created if it does not exist |
--dry-run | Plan the backup and print a summary without writing any data |
--delete-stale | Remove local mbox messages that no longer exist on the server |
Each IMAP folder is written to a separate .mbox file inside DEST-PATH. Backups are incremental: only messages with a UID higher than the last recorded watermark are fetched. Re-running the command picks up new mail only.
Examples:
# Full backup
inboxferry-cli backup work ~/Mail/work
# Incremental backup (run again; only new mail is fetched)
inboxferry-cli backup work ~/Mail/work
# Preview what would be fetched
inboxferry-cli backup work ~/Mail/work --dry-run
# Remove local copies of server-deleted messages
inboxferry-cli backup work ~/Mail/work --delete-stale
# Quiet mode for cron
inboxferry-cli --quiet backup work ~/Mail/work
Trial limit: Unactivated builds back up at most 100 messages per run. Run the command again to continue; the watermark is updated after each run.
migrate
Migrate mail between accounts or from local files into an IMAP account.
migrate imap
Copy mail from one IMAP account to another.
inboxferry-cli migrate imap SRC-ACCOUNT-ID DST-ACCOUNT-ID [OPTIONS]
| Argument / Option | Description |
|---|---|
SRC-ACCOUNT-ID | Source account ID |
DST-ACCOUNT-ID | Destination account ID |
--src-folder TEXT | Migrate only this source folder (default: entire account) |
--dst-folder TEXT | Write into this destination folder (default: same name as source) |
--dry-run | Plan without writing any data |
--delete-stale | Delete destination messages not present in source |
--exclude-gmail-folders | Skip Gmail aggregator folders ([Gmail]/All Mail, [Gmail]/Starred, etc.) |
The source account is opened read-only — no STORE, EXPUNGE, or APPEND commands are sent to the source server. Flags and INTERNALDATE are preserved on the destination.
Examples:
# Migrate an entire account
inboxferry-cli migrate imap old-gmail new-fastmail
# Migrate a single folder
inboxferry-cli migrate imap old-gmail new-fastmail \
--src-folder INBOX --dst-folder Archive/Gmail
# Gmail → anything: skip aggregator views
inboxferry-cli migrate imap gmail-work exchange-work \
--exclude-gmail-folders
# Dry run first, then execute
inboxferry-cli migrate imap old new --dry-run
inboxferry-cli migrate imap old new
migrate mbox
Upload messages from a local .mbox file into an IMAP folder.
inboxferry-cli migrate mbox MBOX-FILE DST-ACCOUNT-ID DST-FOLDER [OPTIONS]
| Argument / Option | Description |
|---|---|
MBOX-FILE | Path to the .mbox file |
DST-ACCOUNT-ID | Destination account ID |
DST-FOLDER | Destination IMAP folder name (created if absent) |
--dry-run | Plan without uploading |
Example:
inboxferry-cli migrate mbox ~/export/inbox.mbox my-fastmail INBOX
migrate maildir
Upload messages from a Maildir directory into an IMAP folder.
inboxferry-cli migrate maildir MAILDIR-PATH DST-ACCOUNT-ID DST-FOLDER [OPTIONS]
| Argument / Option | Description |
|---|---|
MAILDIR-PATH | Path to the Maildir directory (contains cur/, new/, tmp/) |
DST-ACCOUNT-ID | Destination account ID |
DST-FOLDER | Destination IMAP folder name (created if absent) |
--dry-run | Plan without uploading |
Example:
inboxferry-cli migrate maildir ~/Maildir/INBOX my-account INBOX
restore
Restore a backup directory into an IMAP account.
inboxferry-cli restore BACKUP-DIR DST-ACCOUNT-ID [OPTIONS]
| Argument / Option | Description |
|---|---|
BACKUP-DIR | Root backup directory produced by backup (contains .mbox files) |
DST-ACCOUNT-ID | Destination account ID |
--prefix TEXT | Prepend this prefix to every restored folder name |
--dry-run | Plan without uploading |
Each .mbox file in BACKUP-DIR is mapped to the corresponding IMAP folder on the destination server. Use --prefix to restore into a sub-folder namespace (e.g. Restored/2024).
Examples:
# Restore into the same folder structure
inboxferry-cli restore ~/Mail/backup/work new-account
# Restore under a prefix
inboxferry-cli restore ~/Mail/backup/work new-account --prefix "Restored/work"
# Preview before restoring
inboxferry-cli restore ~/Mail/backup/work new-account --dry-run
Using –config-dir
Point inboxferry-cli at a different configuration directory — useful for multiple profiles or for scripting against a non-default install:
inboxferry-cli --config-dir /etc/inboxferry backup work-server /var/backup/mail
The directory must contain a valid config.toml file (created by the GUI or by hand).
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Error (printed to stderr) |
Scripting and automation
inboxferry-cli is designed for use in cron jobs and shell scripts:
#!/bin/sh
# Daily backup cron job — add to crontab:
# 0 2 * * * /usr/local/bin/backup-mail.sh >> /var/log/inboxferry.log 2>&1
inboxferry-cli --quiet backup work ~/Mail/work
inboxferry-cli --quiet backup personal ~/Mail/personal
Use --quiet (-q) to suppress progress output; error messages still go to stderr. Exit code 0 means all selected mail was processed without error.