Configuration

The settings view

Most of what follows can be changed without leaving the client: :settings opens a tabbed view over accounts and the daily-driver preferences, walked through step by step in the settings view. The files below remain the source of truth; the settings view is a well-mannered editor of them, nothing more.

Everything lives under $XDG_CONFIG_HOME/antiphon (defaulting to ~/.config/antiphon on Linux and macOS alike):

config.toml          global settings
accounts/*.toml      one file per account
local.toml           per-machine overrides, loaded last
signatures/<name>    signature files referenced by name
templates/<name>     compose templates referenced by name

Templates named new and reply, when present, shape fresh composes and replies automatically; :template <name> opens a fresh compose from any named template. Tokens {from}, {name}, {date} and {quoted} expand; unknown braces pass through.

Parsing is strict: an unknown key fails with the file, the line, and the nearest valid key. Empty or relative XDG variables are ignored per the specification. No secrets belong in any of these files; passwords come from password_cmd.

local.toml holds the same keys as config.toml and wins where both set a value; defects in it are reported against local.toml.

config.toml

[ui]
theme = "vespers"          # or a gallery name, see below
reading_pane = "below"     # below | right | off
date_format = "%Y-%m-%d %H:%M"  # chrono strftime
composer = "embedded"      # embedded terminal pane for the
                           # editor, or "suspend" to hand the
                           # whole screen over
accounts_bar = "sidebar"   # sidebar | tabs; see below
list_rows = 7              # message rows when the reading
                           # pane is below; with "right" or
                           # "off" the list fills the height
                           # and this key does not apply
sidebar_width = 16         # columns, clamped to 10-40
headers = ["from", "to", "date", "subject"]
                           # headers the pager and reading
                           # pane show, in this order; any
                           # RFC 5322 name is legal, matched
                           # case-insensitively (x-mailer,
                           # message-id, ...)
inline_images = true       # render a message's images inline
                           # in the reading pane

[accounts]
order = ["work", "personal"]  # rank accounts; first is
                              # primary, see below

[export]
recipients = ["age1..."]   # age keys :export encrypts to;
                           # see the export guide

[compose]
request_dsn = false        # ask for a delivery status
                           # notification (RFC 3461) on new
                           # mail; toggle it per message on
                           # the review screen

[vault]
backend = "auto"           # auto | luks2 | apfs | gocryptfs
passphrase_cmd = "pass show antiphon/vault"  # unlock secret
yubikey_pin_cmd = "pass show antiphon/fido2-pin"  # FIDO2 PIN
idle_lock_minutes = 0      # seal after N client-less
                           # minutes; 0 = never
unlock = ["passphrase"]    # methods to try, in order:
                           # passphrase, touchid, yubikey

[sync]
interval_minutes = 2       # periodic daemon sync; 0 disables
idle = false               # IMAP IDLE push on each INBOX

[daemon]
autostart = true           # client starts antiphond if absent

[notifications]
enabled = true             # desktop notification on new mail
folders = ["INBOX"]        # folders that raise one; empty
                           # watches every folder
sound = false              # play a sound with the notification
speech = false             # speak the sender and subject

[keys]
# action = "key sequence"; every action is rebindable,
# see the keys page for the full action list
half-page-down = "ctrl-f"
sync = ",s"

[[saved_searches]]
name = "unread"
query = "tag:unread"

Built-in themes: vespers (default), kanagawa-wave, catppuccin-mocha, catppuccin-latte, gruvbox-dark, gruvbox-light, tokyo-night, nord, rose-pine, dracula, solarized-dark, solarized-light, one-dark, everforest-dark, ayu-dark, github-dark, monokai. :theme with no name lists them; truecolor terminal required.

In the message list the rendered date_format splits at its last space: the left part wears the theme's date colour, the right its time colour, whatever strftime pattern you set; a single-token format is coloured entirely as a date.

[accounts] order lists account names to place first, in that order, everywhere accounts appear: the sidebar, the tab bar, account cycling and unified queries. Unlisted accounts follow, alphabetically by file name. The first account is the primary: it is selected on startup, and a fresh compose in the unified view sends from it (a scoped view's fresh compose uses the account in view). Shift-J/K on the settings Accounts tab edit the same list in place.

accounts_bar chooses how accounts are presented: "sidebar" (the default) nests every account's folders in the sidebar, "tabs" puts a one-line bar of tabs above the panes instead; see appearance. The settings Essentials tab toggles it live.

The vault seals the store at rest (see the vault): antiphon vault create sets it up, passphrase_cmd supplies the unlock secret to antiphond, and an absent vault leaves the store an ordinary directory. unlock lists the methods to try in order, defaulting to ["passphrase"]. Enrol Touch ID on macOS with antiphon vault touchid-enrol, or a YubiKey with antiphon vault yubikey-enrol (a primary and a backup key both open the vault with one touch), then add touchid or yubikey to the list. The YubiKey's FIDO2 PIN comes from its own yubikey_pin_cmd, kept apart from passphrase_cmd so the two secrets never share a source. A hardware method that fails falls through to the next, never past the vault.

[export] recipients lists the age public keys the client's :export command encrypts to; the command refuses until at least one is set. The command line can encrypt to a passphrase instead; see export and archives.

[compose] request_dsn sets whether a new message starts with a delivery status notification (DSN, RFC 3461) requested, and defaults to false. The review screen's n toggles it per message, and a server only sees the request when it advertises the DSN ESMTP extension.

Compose behaviour (:sign overrides, templates, drafts) is covered with the rest of composing in templates and signatures and the writing guide.