Settings

Settings is a full-screen panel opened from the main TUI. It lets you adjust configuration without manually editing YAML for common account, AI, sync, and cleanup fields.

Overview

Press S from the main UI to open settings. The panel reads the current config, lets you edit supported fields, writes the config path, updates AI provider details, and can trigger OAuth wait behavior for supported experimental flows.

Screen Anatomy

Area	What it shows
Account/provider fields	Vendor, username, password/app password, and provider-specific options.
IMAP fields	Host, port, and related server settings.
SMTP fields	Host, port, and send settings.
AI provider fields	Ollama local/custom, Claude, OpenAI-compatible, or disabled.
AI model fields	Chat/classification model and embedding model.
Sync fields	Poll interval minutes and IMAP IDLE setting.
Cleanup fields	Cleanup schedule hours and related automation timing.
Save/cancel controls	Form-level completion or cancellation behavior.
OAuth wait overlay	URL/open-browser state while waiting for OAuth callback and token storage.

Controls

Key	Context	Preconditions	Result
`S`	Main UI	Settings closed.	Opens settings panel.
`tab`	Settings form	A form field is active.	Moves through form controls according to the form component.
`enter`	Settings form	Current field or form action is valid.	Accepts selection, advances, or saves when on final action.
`esc`	Settings form	Settings active.	Cancels/closes panel when supported by current form state.
`enter`	OAuth wait overlay	OAuth URL available.	Opens browser to the authorization URL.
`ctrl+c`	Any settings state	Any state.	Quits Herald.

Workflows

Open and Save Settings

Press S.
Move through fields with form navigation.
Update provider, server, SMTP, AI, sync, or cleanup fields.
Save the form.
Herald writes config and applies runtime changes that can be applied immediately.

Change AI Provider

Press S.
Choose an AI provider.
Enter host, model, API key, or compatible base URL as required.
Save.
Watch the AI status chip after returning to the main UI.

Start OAuth

Choose an OAuth-capable provider path.
Start the OAuth flow.
In the OAuth wait overlay, press enter to open the browser.
Complete provider consent.
Wait for Herald to save token data and return to the app.

States

State	What happens
Panel mode	Settings replaces the normal tabs until saved or cancelled.
First-run mode	Settings/wizard completion is required before the main mailbox opens.
OAuth waiting	Herald shows authorization URL state and waits for callback.
OAuth saved	Token data is written to config.
AI model changed	Herald may reset embeddings so stale vectors do not mix with a new embedding model.
Config permission warning	Startup warns if group/other users can read the config file.
Save error	The panel reports an error if config cannot be written.

Data And Privacy

Settings reads and writes credentials, app passwords, OAuth tokens, server hosts, SMTP settings, AI provider keys, model names, sync options, cleanup schedule, and cache path values. OAuth refresh tokens and external AI keys should be treated as credentials.

Troubleshooting

If settings will not save, check file permissions for the config path and parent directory.

If OAuth does not complete, copy the displayed URL into a browser, finish consent, and confirm the callback server is reachable.

If AI stops working after model changes, verify the new model is installed or reachable and allow embedding regeneration to complete.