The cache

This page shows how to use the mail cache from the command line: search it, fill it, update it and delete it. The cache is a local copy of the headers and the text of your mail, and it makes the search fast.

All four commands need enabled = true in [cache] (see The mail cache) and take the id of an account as it is written in config.toml. Close Tilde first for reset, rebuild and build: two programs would write the same cache file.

Search

tcli cache search work "invoice november"
tcli cache search work boiler --limit 10

The command searches the sender, the subject and the text of what the cache of work holds. It does not connect to a server, so it works offline. Case and accents do not matter, every word must match and each word matches as a prefix. Nothing you type is read as a search operator.

1793894124.2_1.host  2026-11-07 12:00  INBOX  Bob <bob@example.org>  Lunch
Found 1 message.

Each hit is one line, the best match first: id, date, folder, sender and subject. --limit is the most hits it prints (50 by default). The id is the one that tcli read takes. A text with no hit still exits with 0: the cache holds only what was read, so fill it first (see below). A text with no letter or digit, such as ***, is a usage error.

Fill the cache

tcli cache rebuild work

rebuild empties the cache of the account and fills it again, so the search finds the sender and the subject of the whole mailbox, not only of what you have read. It logs in, reads the folders and then the headers of every folder in windows of 500 messages, and prints one line for each folder.

The cache of the account was emptied.
INBOX: 2 messages, 2 bodies.
Rebuilt the cache of 'work': 1 folders, 2 messages, 2 bodies.

While it works it prints a status line every second, such as work: INBOX 1500/48200 (folder 1 of 12). Ctrl-c stops it with exit code 130, and what was read stays in the cache.

Index the text of the messages

The text (the bodies) is indexed too for a Maildir account: the files are read from the disk and stay where they are. For a remote account such as IMAP it is not the default, because every message is downloaded one by one and kept only within size_max. Two options change that:

tcli cache rebuild work --bodies
tcli cache rebuild work --no-bodies

--bodies asks for the text on a remote account and --no-bodies leaves it out on a Maildir account. Giving both is a usage error. A Maildir reads several files at once; --jobs 4 says how many (the default is the number of processors, at most 8, and --jobs below 1 is a usage error).

Update the cache

tcli cache build work

build does the same work without emptying the cache, so a second run only does the new work. It reads the folders and the headers again, drops the messages that are gone, and indexes the text only of the messages that have none yet. The line of each folder says how many are new: INBOX: 48210 messages, 12 new bodies. It takes --bodies, --no-bodies and --jobs like rebuild.

Delete the cache

tcli cache reset work

reset deletes the cache file of the account, the same as the cache.reset command of Tilde. Restart Tilde to use the cache of the account again.

When it fails

A message or a folder that cannot be read is shown and the others go on; the exit code is then 1. A cache file that is refused, for example after a change of encrypt_key, is made again by rebuild; build does not delete it and tells you to use rebuild. An account that is not in the file, or a cache that is off, stops the command before it touches anything.

Every option is in the reference of tcli.