Local sync

By default every command asks your mail server. Local sync keeps a copy of message headers and flags (sender, recipients, subject, date, read status, attachment marker) in a database on your machine. Commands with --cached read that copy instead: fast, and it works offline.

It's optional, and it never runs on its own. The copy updates only when you run sync run.

Sync#

fob-email sync run                         # INBOX of the current account
fob-email sync run --folder Archive
fob-email sync run --all-folders           # every folder
fob-email sync run --all-accounts          # every account in the config file
fob-email sync run --limit 5000            # first sync: only the newest 5,000 messages

• The first sync of a folder fetches everything, unless you pass --limit. For a large mailbox, start with --limit.
• Later syncs fetch only what changed: new messages, changed flags, and deletions.
• --full ignores what's stored and syncs the folder from scratch.
• If your provider renumbers a folder, the next sync rebuilds it and reports reset.
• If some folders fail with --all-folders, the others still sync. The failures print on stderr and the command exits 1.

Read from the copy#

fob-email emails list --cached
fob-email emails list --cached --unseen --folder Archive
fob-email emails search --cached --from aws --since 2026-01-01

• Every --cached read prints how old the copy is, such as (cached — synced 3h ago), on stderr.
• --cached never falls back to the server. If the folder was never synced, the command fails and tells you which sync run to run.
• The copy has no message bodies, so search --cached can match --from, --subject and --since, but not a text query. emails show, download and threads always read live.

Check and clear#

fob-email sync status                      # folders, message counts, last sync
fob-email sync status --all-accounts
fob-email sync clear --yes                 # delete the local copy (your mail is untouched)
fob-email sync clear --folder Archive --yes

sync status reads only the local database, so it works offline.

Where it's stored#

The copy lives in ~/.fob/fob-email/sync.db, next to your config file, with mode 0600. It holds senders, recipients and subjects, so treat it like your mail. It's safe to delete: sync clear or removing the file loses nothing, and the next sync run rebuilds it.

Sync only ever copies from your server to your machine. Nothing in the local copy is sent back, so a failed or interrupted sync can leave the copy out of date, but never changes your mailbox.

Node.js may print an ExperimentalWarning about SQLite on stderr. It's harmless, and doesn't affect stdout.