Skip to content

Key Binds ​

Key Binds allow you to map user input (Triggers) to one or more operations (Actions).

Triggers ​

A trigger is the event that activates a binding. Matchmaker supports keyboard, mouse, and semantic aliases.

Keyboard ​

Standard key names and combinations are supported. Matchmaker uses a very human format:

  • Single Keys: enter, esc, space, tab, backtab, backspace, insert, delete, up, down, left, right, pageup, pagedown, home, end, hyphen (or minus), f1 through f24.
  • Characters: a, b, c, 1, 2, 3, ?, /, etc.
  • Modifiers: ctrl-, alt-, shift-, cmd- (the super key), e.g. ctrl-c, alt-enter, shift-up.
  • Combinations: ctrl-alt-del.

Get your key name with mm --test-keys.

Example:ctrl-s = "Select" (Bind Ctrl+S to the Select action)

Mouse ​

The following mouse events can be bound:

  • Buttons: left, middle, right.
  • Scrolling: scrollup, scrolldown, scrollleft, scrollright.
  • Modifiers: ctrl+left, alt+scrollup, shift+right.

Modifiers can be specified but are not supported due to a library limitation.

Example:scrollup = "Up(1)" (Bind ScrollUp to move the cursor up 1 line)

Semantic Triggers ​

Semantic triggers (prefixed with @) act as named aliases. They allow you to define a sequence of operations once and trigger it from multiple keys or events, or even from other actions.

Allowed Characters: Semantic trigger names (the part after @) can contain:

  • Alphanumeric characters
  • Spaces
  • -, _, ., :, /, +, @, $

Defining a Semantic Trigger:

You define a semantic trigger by binding it to one or more actions in your configuration:

toml
[binds]
"@my_macro" = [
    "ExecuteSilent(echo 'Starting...')",
    "Filtering(true)",
    "SetPrompt(working> )",
]

Using a Semantic Trigger:

This trigger then becomes a valid action:

toml
[binds]
"ctrl-x" = "@my_macro"
"Start" = "@my_macro"

When sharing a command-line matchmaker command, you can also define your actions using these semantic triggers, allowing consumers to use their preferred binds for similar actions across different applications.

Note: You can also dynamically rebind semantic triggers at runtime using the Bind action. For an advanced example, scroll to the bottom.

Predefined Semantic Triggers:

When start.additional_commands is non-empty, @next and @prev are seeded with the following defaults unless you (or a preset) redefine them:

toml
[binds]
# cycle through the reload commands in `start.additional_commands`
"@next" = ["ReloadNext", "ClearQuery"]
"@prev" = ["ReloadPrev", "ClearQuery"]

@help is seeded with a default action unless you (or a preset) redefine it: it pages the preset docs (falling back to the file's leading comment block) fullscreen with your configured pager, followed by the bindings.

The default config also defines ordinary aliases such as @accept, @open, @reload, @print, and @copy; presets commonly add more (e.g. @return). These are config conventions, not built-in actions.

Events ​

Actions can be bound to events:

Lifecycle ​

  • Start – Triggered when the application starts.
  • Synced – Triggered when the matcher completes its first synchronization.
  • Resynced – Triggered when the matcher finishes processing the current state again.
  • Reloaded – Triggered when a Reload or ReloadNext action begins.
  • Restarted - Triggered when the matcher starts running again.

Input & Cursor ​

  • QueryChange – Triggered whenever the input query changes.
  • CursorChange – Triggered when the selection cursor moves.
  • CursorLost – Triggered when there is no current result.

Preview & Overlay ​

  • PreviewChange – Triggered when the preview content updates.
  • PreviewSet – Triggered when preview content is explicitly set.
  • OverlayChange – Triggered when the overlay content changes.
  • PreviewStarted - When the preview command for a result starts running.
  • PreviewFinished - When a preview finishes.

Window ​

  • Resize – Triggered when the terminal window is resized.
  • Redraw – Triggered when a full UI redraw is requested.
  • Tick – Periodic UI tick; also sent when a background image finishes decoding.

Control ​

  • Pause – Triggered when the system enters a paused state.
  • Resume – Triggered when execution resumes from a paused state.

Modes ​

Triggers can be optionally prefixed with a mode pattern followed by ^^. A bind with a mode will only be active when the current application mode matches the pattern.

Syntax: mode_pattern^^trigger = actions

The mode pattern uses a prefix-based filter:

  • Positive prefixes (e.g., 0, vim): The current mode must contain a tag starting with this prefix.
  • Negative prefixes (e.g., !0, !piped): The current mode must NOT contain a tag starting with this prefix.
  • Multiple prefixes are separated by commas and all must match (AND logic).
  • Omit the pattern to match every mode. An empty prefix (^^enter) is rejected.
  • For the same trigger, a bind with more patterns shadows one with fewer; ties favor the later definition, so your config wins over built-in defaults.

Example:

toml
[binds]
"vim^^h" = "BackwardChar"
"vim^^l" = "ForwardChar"
"h" = "Up"
"l" = "Down"

In this example, if the mode is vim, h and l will move the cursor horizontally. In any other mode, they will move the selection cursor vertically.

More complex examples:

toml
[binds]
# Only active when both stdin and stdout are terminals
"0,1^^enter" = "Accept"

# Active in any mode EXCEPT when stdin is a terminal
"!0^^esc" = "Quit(1)"

# Active when mode contains "vim" but not "insert"
"vim,!insert^^h" = "BackwardChar"

Binds defined without a mode act as fallbacks and are active in all modes unless overridden by a mode-specific bind.

Matchmaker initializes with a default mode based on how it was started. The mode is a comma-separated list of tags:

  • 0,1: Both stdin and stdout are connected to a terminal (full TTY).
  • 0: Only stdin is connected to a terminal (input is interactive, output is piped).
  • 1: Only stdout is connected to a terminal (input is piped, output is interactive).
  • "" (empty): Neither input nor output are connected to a terminal (fully piped).

You can set the initial mode using start.mode.

Scroll to the bottom for some examples.


Actions ​

Actions are the operations performed when a trigger is activated.

Selection ​

ActionDescription
SelectAdd the current item to the selections.
DeselectRemove the current item from the selections.
ToggleSelection / ToggleToggle the selection state of the current item.
CycleSelections / CycleToggle selection for all items in the current view.
ClearSelections / ClearClear all active selections.
AcceptAccept the current selection and exit.
Quit(code)Exit Matchmaker with the specified exit code (default: 0).
ActionDescription
Up(n)Move selection cursor up by n lines (default: 1).
Down(n)Move selection cursor down by n lines (default: 1).
Pos(idx)Move selection cursor to absolute index idx. -1 for end.
HalfPageUpScroll the results list up by half the height of the results pane.
HalfPageDownScroll the results list down by half the height of the results pane.
HScroll(n)Horizontally scroll the active column by n. 0 to reset.
VScroll(n)Vertically scroll down the current result by n. 0 to reset.
ToggleWrapToggle line wrapping for the results list.
ToggleHeaderWrapToggle line wrapping for the header.

Preview ​

ActionDescription
NextPreviewCycle through available preview layouts.
PrevPreviewCycle through available preview layouts in reverse order.
Preview(cmd)Show the preview using the provided command.
SetPreview([idx])Set layout idx; without an index, restore the current layout command.
SwitchPreview([idx])Switch to layout idx; without an index, toggle preview visibility.
TogglePreviewWrapToggle line wrapping in the preview window.
ExpandPreview(n)Expand the preview dimension by n (default: 1).
ShrinkPreview(n)Shrink the preview dimension by n (default: 1).
PreviewUp(n)Scroll the preview window up by n lines (default: 1).
PreviewDown(n)Scroll the preview window down by n lines (default: 1).
PreviewHalfPageUpScroll the preview up by half a page.
PreviewHalfPageDownScroll the preview down by half a page.
PreviewHScroll(n)Persistently scroll the preview horizontally by n (0 resets); pans a shown image.
PreviewScroll(n)Persistently scroll the preview vertically by n (0 resets); zooms a shown image by n tenths instead.
PreviewJumpJump between the preview's start, end, and initial locations.
RunPreview(cmd)CLI action: run a one-off command and display its output in the preview.
ShowPreview([cmd])Page the current preview command (or cmd) fullscreen; the picker resumes when the pager exits.
Help(section)Display the specified help section in the preview.

Columns ​

ActionDescription
NextColumnMove focus to the next column.
PrevColumnMove focus to the previous column.
SwitchColumn(col)Focus column specified by name or index.
HideColumn([col])Hide the named column (or the active column); the default column cannot be hidden.
UnhideColumn([col])Unhide the specified or most recently hidden column.
ExpandColumn([n])Widen the n-th (0-based) non-hidden column by 1; omitted widens the active column.
ShrinkColumn([n])Narrow the n-th (0-based) non-hidden column by 1; omitted narrows the active column.

Sorting ​

Sort the results by one of the columns in the active row.

ActionDescription
Sort(n)Sort ascending by the active or given (0-based display) column lexicographically.
SortNumeric(n)Same as Sort but parses column as a number.
SortThreshold([n])Set matcher stability to n; omitted restores maximum stability.
SortReverse([bool])Reverse the non-match scoring function; omitted toggles the direction*.

*: This is not the same as reversing the sort direction.

ActionDescription
ForwardCharMove cursor one character forward.
BackwardCharMove cursor one character backward.
ForwardWordMove cursor one word forward.
BackwardWordMove cursor one word backward.
DeleteCharDelete the character under the cursor.
DeleteWordDelete the word before the cursor.
DeleteLineStartDelete from cursor to the start of the line.
DeleteLineEndDelete from cursor to the end of the line.
ClearQueryClear the entire input query.
ClearQueryLeft / CancelDelete from the start of the query to the cursor.
ClearQueryRightDelete from the cursor to the end of the query.
SetQuery(s)Replace the input query with s.
InsertQuery(s)Insert s at the query cursor.
QueryPos(n)Move the input cursor to position n.
Filtering([bool])Toggle or set whether input filters results (default: true).
HistoryUpTODO: move to the previous query history entry.
HistoryDownTODO: move to the next query history entry.

Binds (Dynamic) ​

ActionDescription
Bind(trigger=actions)Define or overwrite a binding at runtime.
Unbind(trigger)Remove a binding.
PushBind(t=a)Append an action to an existing binding.
PopBind(t)Remove the last action from a binding.

Modes ​

ActionDescription
PushMode(s)Push a mode tag onto the mode stack.
SetMode(s)Replace the current mode stack with s.
PopMode(s)Pop last tag, or remove a specified tag s.

Programmable and Miscellaneous ​

ActionDescription
Execute(cmd)Run a shell command.
ExecuteSilent(c)Run and detach a shell command silently.
ExecuteAsync(cmd)Run in the background; subsequent actions in the same batch execute after its completion.
ExecuteThen(cmd)Run in the background; subsequent actions execute after completion and only if it succeeds.
CopyAsync(cmd)Run a command asynchronously and copy its output to the clipboard (works across ssh: see tui.osc52).
Copy(cmd)Same as CopyAsync but run synchronously. Use in chained actions which exit on completion
ExecuteOrConfirm(c)Run a shell command, and prompt for confirmation if failed.
ExecuteAndQuit(cmd)Run a shell command, and quit on success.
Become(cmd)Transform the process into the command.
BecomeSilent(cmd)Transform the process into the command without clearing the screen (useful for transitioning between different matchmaker presets).
BecomeOrConfirm(cmd)Execute the command, quit on success, ask for confirmation on failure, resume on user-originated termination or exit code 100.
BecomeOrResume(cmd)Execute the command, quit on success, resume on failure, exit on any nonstandard termination.
Reload(cmd)Rerun the initial command or a new one.
ReloadNext([n])Cycle through additional_commands; an optional n selects a specific command index.
ReloadPrevCycle backwards through additional_commands.
Transform(cmd)Run command and parse its output as a stream of Actions.
TransformConfig(cmd)Run command and parse its output as configuration pairs (analogously to the cli input, one per line).
Store(str)Set the value of MM_STORE.
Print(s)Print a string to stdout.
PrintKeyPrint the activating key.
@nameExecute the actions associated with semantic trigger name.
#descriptionAdd a description-only trace action for help/debug output.

Note: Commands executed via these actions have access to various environment variables and multiple execution models (shell, @file, #!lua, @file.lua). See Execution Models (mm --doc execute) for full execution strategy and lifecycle details. CLI command actions use the configured start.shell; an empty shell uses $SHELL (falling back to /bin/sh). A command beginning with @ treats the first word as a script path relative to the parent of MM_OVERRIDE (absolute paths are also accepted) and passes the remaining words as arguments without shell parsing.

UI & Display ​

ActionDescription
SetHeader([str])Set the header text; omit or pass empty to clear.
PushHeader(str)Append a column to the header.
SetFooter([str])Set the footer text; omit or pass empty to clear.
PushFooter(str)Append a column to the footer.
SetPrompt([str])Set the input prompt text; omit or pass empty to restore/clear.
SetStatus([str])Set the status line template; omit or pass empty to restore/clear.
SetStyledPrompt(s)Update the input prompt.
SetStyledStatus(s)Update the status line.
Toast(msg)Push a new toast entry: prefix:message, or just message without a prefix. The message supports the status line's style templates, without placeholders.
ToastJoin(msg)Join a message onto the last toast with the same prefix, separated by ,.
ClearToastClear the toast log.

* See mm --doc template

Other & Experimental ​

ActionDescription
Overlay(idx)Activate the UI overlay at index idx.
RedrawForce a complete UI redraw.
ToggleExitFirst([bool])Toggle (or explicitly set) exit.first.

Sequences and CLI ​

Multiple actions can be executed in sequence by using an array:

  • TOML: ctrl-x = ["Cancel", "Reload"]
  • CLI: mm b "ctrl-x=Cancel,Reload"

CLI Overrides ​

When overriding binds from the command line, use the b (or binds) prefix. The map form is b '<trigger>=<actions>'; the path form is b.<trigger> <actions>, which avoids ambiguity when the trigger contains = or .:

bash
# Bind a single action:
mm b 'alt-enter=Accept'

# Some action parameters are optional
mm b.ctrl-q 'SwitchPreview' # toggle preview
mm b.ctrl-q 'SwitchPreview(2)' # toggle preview layout 2

Action lists are comma-separated in both forms. To keep a comma inside an action payload, double it (a,,b).

Advanced Example: Switching between Ripgrep and MM ​

You can mimic fzf's ripgrep example as follows:

toml
[query]
prompt_style.fg = "Red"

[matcher]
ansi = true

[start]
command = 'rg --column --line-number --no-heading --color=always --smart-case "$FZF_QUERY"'

[binds]
"Start" = "@enter_rg"
"@enter_rg" = [ # Reload on query change, disable reparsing, update bind
    "Filtering(false)",
    '''Bind(QueryChange = Reload)''',
    # Prompt indicator (
    '''Transform(
    [[ -n "$MM_QUERY" ]] &&
    prompt="($MM_QUERY)" ||
    prompt="rg>"

    echo "SetPrompt($prompt )"
    echo "SetQuery($MM_STORE)"
    echo "Store($MM_QUERY)"
)''',
    "Bind(@reload = @enter_mm)",
]
"@enter_mm" = [
    "Filtering(true)",
    "Unbind(QueryChange)",
    '''Transform(
 [[ -n "$MM_QUERY" ]] &&
 prompt="($MM_QUERY)" ||
 prompt="mm"

    echo "SetPrompt({blue,italic:$prompt })"
    echo "SetQuery($MM_STORE)"
    echo "Store($MM_QUERY)"
)
''',
    "Bind(@reload = @enter_rg)",
]

"ctrl-r" = "@reload"

This example is simplified to demonstrate the special actions Bind, Store, Transform, and Semantic. You can find the full version at https://github.com/Squirreljetpack/matchmaker/blob/main/matchmaker-cli/assets/presets/rg.toml