# 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`.

<Callout type="info" title="Needs Node.js 22.13 or later">
Local sync uses the SQLite database built into Node.js. On older versions, `sync` and `--cached` fail and every other command still works. See [Install](/docs/email/cli/install).
</Callout>

## Sync

```bash
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

```bash
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

```bash
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.