This reference lists user-facing keys backed by Herald’s current key handlers and key hints. When a key appears in multiple sections, the most specific focused overlay or panel wins.
These actions work when the terminal sends mouse events to Herald. OSC 8 link clicks are handled by the terminal, so compatible terminals open the real URL while Herald keeps the preview text readable; when mouse motion is available, hovered links brighten in place and the status bar previews the sanitized destination.
Mouse action
Result
Click top tab
Switch to Timeline, Contacts, or Calendar when available.
Click folder/sidebar row
Select and load that folder.
Click Timeline row
Select the message or thread and open the preview.
Scroll Timeline rows
Move the Timeline cursor by small steps.
Scroll Timeline preview
Scroll the message body.
Click Calendar mini-month day
Select that calendar day or range.
Click Calendar event
Select the event. Double-click the same event to open its full detail.
Click Calendar checkbox
Show or hide that calendar and persist the visible-calendar selection in YAML.
Hover OSC 8 email link
Highlight the visible link label and show a short sanitized destination preview in the status bar.
Click or Ctrl-click OSC 8 email link
Open the target URL while Herald mouse navigation is enabled.
Press m in Timeline or Calendar
Release or restore Herald mouse capture for terminal-native text selection.
Herald resolves browse shortcuts through the active keyboard profile. Text-entry surfaces keep printable text literal in the Default profile; Vim and Custom profiles can use the modal Compose field adapter. Default bottom hints show preferred GUI-mail-style keys only, while legacy aliases remain active for at least one release and are listed here and in ? help.
Profile-owned browse scopes include the global, timeline, contacts, calendar, and compose command IDs exposed by the keymap catalog. Literal text-entry fields, editor-style inputs, and fixed confirmation controls keep their local keys so custom browse shortcuts do not steal typed message text, search queries, file paths, prompt text, or yes/no confirmation choices.
keyboard:
profile: default# default | vim | emacs | custom
custom_keymap: ~/.config/herald/keymaps/work.yaml
Custom keymap files extend a built-in profile and bind keys to predefined command IDs:
extends: default
bindings:
timeline:
normal:
x: compose.new
a: mail.archive_current
d: mail.delete_confirm
D: mail.delete_immediate
fields:
compose:
default_mode: normal# insert | normal | visual
Default exposes command IDs for custom keymaps including pane.next, pane.prev, account.switcher, compose.send, compose.attach, and compose.preview. Ctrl+, is intentionally not bound to Settings by default because many terminals do not report it reliably, but custom keymaps may bind it when their terminal does.