Filters and input

Input editing

Readline-style bindings are enabled by default: Ctrl-N/Ctrl-P browse results, Ctrl-D/Ctrl-U move by a visible page, Ctrl-F/Ctrl-B move the cursor, Ctrl-A/Ctrl-E jump to either end, and Ctrl-W deletes the previous word. Every configurable binding accepts one key, a list of keys, or false.

[keybindings]
enabled = true
down = ["down", "ctrl-n"]
up = ["up", "ctrl-p"]
page_down = "ctrl-d"
page_up = "ctrl-u"
accept = "enter"
cancel = "esc"

A configured action menu takes precedence over an overlapping input binding. Move actions.menu away from Ctrl-A if you want to keep start-of-input on that key.

Vim mode

Vim input is enabled and starts in insert mode by default:

[input]
vim = true
start_mode = "insert"

Escape changes insert to normal; Escape again closes Vellum. Normal mode supports h, l, b, w, 0, $, x, i, a, I, A, j, and k. Ctrl-C always cancels. The footer badge and terminal cursor show the current mode.

Exact-match filters

Filters combine with fuzzy search and frecency ranking:

[filters]
label = "status"
mode = "ctrl-g"
clear = "a"
cycle_nonempty = true

[[filters.choices]]
key = "w"
label = "working"
source = "state"
value = "in_progress"
icon = "●"
fg = "yellow"

To open a palette with the choice keys immediately available, set start_mode = "filter" in its [input] section. This starts in filter mode when choices are configured, with insert mode underneath. The default start_mode = "insert" requires Ctrl-G before a choice key. Press the active choice again or the clear key to show all items. Another choice replaces the active filter. Escape closes filter mode and returns to insert editing without cancelling; search then combines with the active filter. With no filter choices, start_mode = "filter" falls back to insert editing. Filter sources support dot paths such as metadata.state.

Tab and Shift-Tab cycle through choices with results for the current search, including all when it has results. This updates as live source values change; if no choice has results, cycling leaves the selection alone. Direct choice keys still work for empty choices. Set cycle_nonempty = false under [filters] to cycle through every choice instead.

Set filters.initial to a configured choice’s value, such as initial = "in_progress", to select it at startup. This is independent of whether the filter controls start open, and the choice stays selected even when empty. Unknown initial values are rejected. Remote palettes can use source.remote.probe_filters = true or source-provided availability to dim and skip empty default categories while keeping direct shortcuts available.

[input]
start_mode = "filter"

Choice keys cannot collide with available editing commands while filter mode is open. List navigation remains active.