Logging and jobs

This page shows how to write a log file and how to set the number of background jobs. Both are small tables of config.toml. The complete list of keys is in config.toml: keys, ui, logging, jobs, scripting.

Write a log file

Tilde writes no log file until you ask for one. Add this:

[logging]
log_to_file = true
log_level = "Information"

Key	Meaning	Default
log_to_file	Writes the log to a file.	false
log_level	The lowest level that is written.	"Information"

log_level is one of None, Trace, Debug, Information, Warning, Error and Critical, in any case. None writes nothing. Write the name as text: a number is not accepted.

The file is tilde-<date>.log, for example tilde-20261107.log, in the logs folder of the root folder of Tilde (~/.config/tilde/logs by default). There is one file for each day, and Tilde keeps the last 14. A line looks like this:

2026-11-07 09:30:12.481 [WRN] Tilde.Cache.CachePlugin: The mail cache is not encrypted: set encrypt_key in the [cache] section to encrypt it

The logs name hosts, folders and accounts, so on Linux and macOS Tilde makes the folder readable by you only. Use Debug while you look for a problem and go back to Information afterwards.

Set the jobs

Tilde runs its background work, such as the jobs of scripts, in a pool of workers. A job that fails never stops the others.

[jobs]
workers = 4
stop_timeout = 00:00:10

Key	Meaning	Default
workers	How many jobs run at the same time.	the number of processors minus one
stop_timeout	How long Tilde waits for the running jobs when it stops.	ten seconds

• The default leaves one processor to the interface. A value of zero or less means one worker for each processor, and Tilde never runs fewer than one.
• stop_timeout is a TOML time, hours:minutes:seconds, written without quotes. "00:00:10" in quotes is an error, and tcli check shows it.
• When the time is over, Tilde stops waiting, leaves the jobs that ignore the request behind and logs a warning.

How a script starts a job is on Jobs and timers.

Check the file

tcli check

A key that does not exist, such as log_leve, is listed with its line.