Skip to content

Key Mapping

To customize key mappings, you need to configure input_mapping yaml entry

Defining input_mapping replaces the built-in bindings — it does not add to them

As soon as an input_mapping section is present in your contour.yml, Contour's built-in defaults (Ctrl+Shift+C/Ctrl+Shift+V, the Ctrl+Shift+P command palette, the tab and pane shortcuts, …) are discarded, and only the entries you list are active. Writing an input_mapping section is a declaration that you are defining the full set of bindings.

The contour.yml that Contour generates on first run already contains every default binding written out in full, so editing that section keeps the defaults you did not touch. If you are writing a configuration by hand and want to keep the defaults, start from a generated one (contour generate config) and add your entries to the existing list.

Built-in bindings

A small number of bindings are built in and do not appear in input_mapping:

Binding Action
Ctrl+Tab / Ctrl+PageDown Switch to the tab on the right (wrapping around)
Ctrl+Shift+Tab / Ctrl+PageUp Switch to the tab on the left (wrapping around)
Right mouse button Open the terminal's context menu
Horizontal wheel / two-finger sideways swipe Switch tabs

These are consulted only when your input_mapping does not claim the same key or button, so binding one of them yourself replaces it.

They are built in rather than listed as defaults for the reason given in the warning above: an input_mapping section replaces the built-in list wholesale, and the generated contour.yml writes every default into that section. A binding added to Contour after your configuration file was written would therefore be shadowed by your own file forever. Consulting these after yours is what lets a new binding still reach you, while anything you bind explicitly keeps winning.

Ctrl+Tab is taken from the application

Like Windows Terminal, GNOME Terminal and Konsole, Contour claims Ctrl+Tab for tab switching, so a terminal application that wants it (via the Kitty keyboard protocol) will not receive it. Bind it in your own input_mapping to give it back to the application.

Writing bindings

Each element in the input_mapping represents one key binding, whereas mods represents an array of keyboard modifiers that must be pressed - as well as the key or mouse - in order to activate the corresponding action. Additionally one can filter input mappings based on special terminal modes using the modes option:

  • Alt : The terminal is currently in alternate screen buffer, otherwise it is in primary screen buffer.
  • AppCursor : The application key cursor mode is enabled (otherwise it's normal cursor mode).
  • AppKeypad : The application keypad mode is enabled (otherwise it's the numeric keypad mode).
  • Select : The terminal has currently an active grid cell selection (such as selected text).
  • Insert : The Insert input mode is active, that is the default and one way to test that the input mode is not in normal mode or any of the visual select modes.
  • Search : There is a search term currently being edited or already present.
  • Trace : The terminal is currently in trace-mode, i.e., each VT sequence can be interactively single-step executed using custom actions. See TraceEnter/TraceStep/TraceLeave actions.

You can combine these modes by concatenating them via | and negate a single one by prefixing with ~. The modes option defaults to not filter at all (the input mappings always match based on modifier and key press/mouse event). key represents keys on your keyboard, and mouse represents buttons as well as the scroll wheel.

Modifiers, which are case-insensitive (Control, control and CONTROL are the same modifier):

  • Shift
  • Alt
  • Control — may also be written Ctrl
  • Super — may also be written Meta. This is the Windows key on Windows, the Command key on macOS, and the Super key on anything else.
  • Hyper

Note

Meta is a synonym for Super for historical reasons: contour.yml has spelled the Windows/Command key Meta since before a separate Meta modifier existed. There is currently no configuration spelling for the distinct Meta modifier that the extended CSI u keyboard protocol reports.

An entry naming a modifier that is not in this list is rejected as a whole — the binding is dropped rather than bound with a partial chord — and the reason is reported on startup.

Keys can be expressed case-insensitively symbolic:

APOSTROPHE, ADD, BACKSLASH, COMMA, DECIMAL, DIVIDE, EQUAL, LEFT_BRACKET, MINUS, MULTIPLY, PERIOD, RIGHT_BRACKET, SEMICOLON, SLASH, SUBTRACT, SPACE Enter, Backspace, Tab, Escape, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, DownArrow, LeftArrow, RightArrow, UpArrow, Insert, Delete, Home, End, PageUp, PageDown, Numpad_Divide, Numpad_Multiply, Numpad_Subtract, Numpad_Add, Numpad_Decimal, Numpad_Enter, Numpad_Equal, Numpad_0, Numpad_1, Numpad_2, Numpad_3, Numpad_4, Numpad_5, Numpad_6, Numpad_7, Numpad_8, Numpad_9

or in case of standard characters, just the character.

A single-character key also matches case-insensitively: key: 'q' and key: 'Q' bind the same chord. Shift is carried by mods, not by the letter's case, so writing an uppercase letter does not mean "with Shift" — use mods: [Shift] for that.

Mouse buttons can be one of the following self-explanatory ones:

Left, Middle, Right, WheelUp, WheelDown, WheelLeft, WheelRight

List of supported actions for key mappings.

Action Description
CancelSelection Cancels currently active selection, if any.
ChangeProfile Changes the profile to the given profile name.
ClearHistoryAndReset Clears the history, performs a terminal hard reset and attempts to force a redraw of the currently running application.
CopyPreviousMarkRange Copies the most recent range that is delimited by vertical line marks into clipboard.
CopySelection Copies the current selection into the clipboard buffer.
CreateDebugDump Create dump for debug purposes
CreateSelection Creates selection with custom delimiters configured via delimiters member.
DecreaseFontSize Decreases the font size by 1 pixel.
DecreaseOpacity Decreases the default-background opacity by 5%.
FocusNextSearchMatch Focuses the next search match (if any).
FocusPreviousSearchMatch Focuses the next previous match (if any).
FollowHyperlink Follows the hyperlink that is exposed via OSC 8 under the current cursor position.
HintMode Activates hint mode: scans the terminal for regex-matched patterns (URLs, file paths, git hashes, etc.), renders short alphabetic labels on each match, and lets the user type a label to act on that match (copy, open, paste). Parameter patterns selects which pattern set to use, hint_action specifies the action (Copy, Open, Paste, CopyAndPaste, Select), and scope selects how much to scan: Visible (the default, the current viewport) or Scrollback (the viewport plus up to hint_scrollback_lines rows of history, whose labels stay put while you scroll to reach them). A pattern that wraps across a line break is matched as one hint.
IncreaseFontSize Increases the font size by 1 pixel.
IncreaseOpacity Increases the default-background opacity by 5%.
NewTerminal Spawns a new terminal at the current terminals current working directory.
NoSearchHighlight Disables current search highlighting, if anything is still highlighted due to a prior search.
OpenCommandPalette Opens the command palette: a searchable popup listing every runnable command with its description and key binding. Recently used commands are listed first, then all commands alphabetically.
OpenConfiguration Opens the in-app settings page (profiles, color schemes, global settings). Set in_editor: true on the binding to instead open the configuration file in an external editor.
OpenFileManager Opens the current working directory in a system file manager.
OpenSelection Open the current terminal selection with the default system application (eg; xdg-open)
PasteClipboard Pastes clipboard to standard input. Pass boolean parameter 'strip' to indicate whether or not to strip repetitive whitespaces down to one and newlines to whitespaces.
PasteSelection Pastes current selection to standard input.Option evaluate_in_shell specify if pasted text must be appended with linefeed and used as an input for the running shell
Quit Quits the application.
ReloadConfig Forces a configuration reload.
ResetConfig Overwrites current configuration with builtin default configuration and loads it. Attention, all your current configuration will be lost due to overwrite!
ResetFontSize Resets font size to what is configured in the config file.
ScreenshotVT Takes a screenshot in form of VT escape sequences.
SaveScreenshot Takes a screenshot and saves it into a file.
CopyScreenshot takes a screenshot and puts it into the system clipboard
CollapseAllFolds Collapses every finished command, hiding all of their output (requires shell integration)
CollapseLastFold Collapses the most recently finished command, hiding its output
ExpandAllFolds Expands every collapsed command again
ScrollDown Scrolls down by the multiplier factor.
ScrollMarkDown Scrolls one mark down (if none present, bottom of the screen)
ScrollMarkUp Scrolls one mark up
ScrollOneDown Scrolls down by exactly one line.
ScrollOneUp Scrolls up by exactly one line.
ScrollPageDown Scrolls a page down.
ScrollPageUp Scrolls a page up.
ScrollToBottom Scrolls to the bottom of the screen buffer.
ScrollToTop Scrolls to the top of the screen buffer.
ToggleFold Collapses or expands the command block the cursor is in
ToggleFoldAt Collapses or expands the command block covering a given grid line (used by the context menu)
ToggleLastFold Collapses or expands the most recently finished command
ScrollUp Scrolls up by the multiplier factor.
SearchReverse Initiates search mode (starting to search at current cursor position, moving upwards).
SendChars Writes given characters in chars member to the applications input.
ToggleAllKeyMaps Disables/enables responding to all keybinds (this keybind will be preserved when disabling all others).
ToggleFullscreen Enables/disables full screen mode.
ToggleInputMethodHandling Enables/disables IME (input method editor) handling.
ToggleInputProtection Enables/disables terminal input protection.
ToggleStatusLine Shows/hides the VT320 compatible Indicator status line.
ToggleTitleBar Shows/Hides titlebar
TraceBreakAtEmptyQueue Executes any pending VT sequence from the VT sequence buffer in trace mode, then waits.
TraceEnter Enables trace mode, suspending execution until explicitly requested to continue (See TraceLeave and TraceStep).
TraceLeave Disables trace mode. Any pending VT sequence will be flushed out and normal execution will be resumed.
TraceStep Executes a single VT sequence that is to be executed next.
ViNormalMode Enters/Leaves Vi-like normal mode. The cursor can then be moved via h/j/k/l movements in normal mode and text can be selected via v, yanked via y, and clipboard pasted via p.
WriteScreen Writes VT sequence in chars member to the screen (bypassing the application).
CreateNewTab Creates a new tab in the terminal emulator.
CloseTab Closes current tab.
MoveTabTo Moves current tab to the given position (starting at number 1).
MoveTabToLeft Moves current tab to the left.
MoveTabToRight Moves current tab to the right.
SwitchToTab Switch to absolute tab position (starting at number 1)
SwitchToPreviousTab Switch to the previously focused tab
SwitchToTabLeft Switch to tab to the left
SwitchToTabRight Switch to tab to the right
SetTabTitle Rename the current tab inline (opens the tab-title editor)
SplitVertical Splits the active pane into two side-by-side panes (a vertical divider).
SplitHorizontal Splits the active pane into two stacked panes (a horizontal divider).
ClosePane Closes the active pane (or the tab if it is the last pane).
FocusPaneLeft Moves pane focus to the left.
FocusPaneRight Moves pane focus to the right.
FocusPaneUp Moves pane focus up.
FocusPaneDown Moves pane focus down.
SwapPaneLeft Swaps the active pane with its left neighbor.
SwapPaneRight Swaps the active pane with its right neighbor.
SwapPaneUp Swaps the active pane with its upper neighbor.
SwapPaneDown Swaps the active pane with its lower neighbor.
MovePaneLeft Moves the active pane past its left neighbor.
MovePaneRight Moves the active pane past its right neighbor.
MovePaneUp Moves the active pane past its upper neighbor.
MovePaneDown Moves the active pane past its lower neighbor.
ToggleSplitOrientation Flips the orientation of the active pane's split (horizontal <-> vertical).
TogglePaneZoom Zooms the active pane so it alone fills the tab, hiding its siblings; toggles back to the tiled layout. While zoomed, moving pane focus keeps the zoom and shows the newly focused pane.
ResizePane Grows or shrinks the active pane in the given direction (by an optional percent).
LaunchLayout Opens a named layout, appending its tabs to the current window.
SaveLayout Saves the current window's tabs as a named layout in layouts.yml. Without a name it opens a prompt to type one in (which is how the command palette offers it).
OpenContextMenu Opens the terminal pane's context menu. Bound to the right mouse button by default, and only fired when the running application has not asked for the mouse itself (hold Shift to open it anyway).
SelectAll Selects everything the terminal holds: the whole scrollback and the whole screen.
SoftReset Performs a terminal soft reset (DECSTR): resets modes, rendition and cursor state, while keeping the screen contents and the scrollback.
CopyLastCommandPrompt Copies the prompt line(s) of the most recently finished command into the clipboard. Requires a shell that emits OSC 133 marks (see Contour's shell integration).
CopyLastCommandOutput Copies what the most recently finished command printed into the clipboard. Requires a shell that emits OSC 133 marks (see Contour's shell integration).
CopyLastCommandBlock Copies both the prompt and the output of the most recently finished command into the clipboard. Requires a shell that emits OSC 133 marks (see Contour's shell integration).
CopyHyperlink Copies the URI of the hyperlink under the mouse cursor into the clipboard.
SetTabColor Colorize the current tab. Without a color, this opens the tab's color picker; with one (e.g. color: '#ff0000') it applies that color right away.
ResetTabColor Removes the color you gave the current tab, restoring its default look (or the color the running application assigned, if it assigned one).
CloseAllTabs Closes every tab in this window. With only one window open, that closes Contour.
SetTabBarVisibility Sets when this window's tab bar is shown (mode: always, never or multiple). Applies to this window until it is closed; the settings page is where the choice is made permanent.
SetTabBarPosition Places this window's tab bar above or below the terminal (position: top or bottom). Applies to this window until it is closed; the settings page is where the choice is made permanent.
SpeakSelection Reads the selected text aloud through the operating system's speech synthesizer. Available only where a speech engine and a voice are installed.
StopSpeaking Stops reading aloud.

Example of entries inside config file 

 - { mods: [Control], key: Enter, action: CancelSelection }
 - { mods: [Control], key: Enter, action: ChangeProfile }
 - { mods: [Control], key: Enter, action: ClearHistoryAndReset }
 - { mods: [Control], key: Enter, action: CopyPreviousMarkRange }
 - { mods: [Control], key: Enter, action: CopySelection }
 - { mods: [Control], key: Enter, action: CreateDebugDump }
 - { mods: [Control], key: Enter, action: CreateSelection, delimiters: '' }
 - { mods: [Control], key: Enter, action: DecreaseFontSize }
 - { mods: [Control], key: Enter, action: DecreaseOpacity }
 - { mods: [Control], key: Enter, action: FocusNextSearchMatch }
 - { mods: [Control], key: Enter, action: FocusPreviousSearchMatch }
 - { mods: [Control], key: Enter, action: FollowHyperlink }
 - { mods: [Control], key: Enter, action: HintMode }
 - { mods: [Control], key: Enter, action: IncreaseFontSize }
 - { mods: [Control], key: Enter, action: IncreaseOpacity }
 - { mods: [Control], key: Enter, action: NewTerminal }
 - { mods: [Control], key: Enter, action: NoSearchHighlight }
 - { mods: [Control], key: Enter, action: OpenCommandPalette }
 - { mods: [Control], key: Enter, action: OpenConfiguration }
 - { mods: [Control], key: Enter, action: OpenFileManager }
 - { mods: [Control], key: Enter, action: OpenSelection }
 - { mods: [Control], key: Enter, action: PasteClipboard }
 - { mods: [Control], key: Enter, action: PasteSelection }
 - { mods: [Control], key: Enter, action: Quit }
 - { mods: [Control], key: Enter, action: ReloadConfig }
 - { mods: [Control], key: Enter, action: ResetConfig }
 - { mods: [Control], key: Enter, action: ResetFontSize }
 - { mods: [Control], key: Enter, action: ScreenshotVT }
 - { mods: [Control], key: Enter, action: SaveScreenshot }
 - { mods: [Control], key: Enter, action: CopyScreenshot }
 - { mods: [Control], key: Enter, action: CollapseAllFolds }
 - { mods: [Control], key: Enter, action: CollapseLastFold }
 - { mods: [Control], key: Enter, action: ExpandAllFolds }
 - { mods: [Control], key: Enter, action: ScrollDown }
 - { mods: [Control], key: Enter, action: ScrollMarkDown }
 - { mods: [Control], key: Enter, action: ScrollMarkUp }
 - { mods: [Control], key: Enter, action: ScrollOneDown }
 - { mods: [Control], key: Enter, action: ScrollOneUp }
 - { mods: [Control], key: Enter, action: ScrollPageDown }
 - { mods: [Control], key: Enter, action: ScrollPageUp }
 - { mods: [Control], key: Enter, action: ScrollToBottom }
 - { mods: [Control], key: Enter, action: ScrollToTop }
 - { mods: [Control], key: Enter, action: ToggleFold }
 - { mods: [Control], key: Enter, action: ToggleFoldAt, line: 0 }
 - { mods: [Control], key: Enter, action: ToggleLastFold }
 - { mods: [Control], key: Enter, action: ScrollUp }
 - { mods: [Control], key: Enter, action: SearchReverse }
 - { mods: [Control], key: Enter, action: SendChars }
 - { mods: [Control], key: Enter, action: ToggleAllKeyMaps }
 - { mods: [Control], key: Enter, action: ToggleFullscreen }
 - { mods: [Control], key: Enter, action: ToggleInputMethodHandling }
 - { mods: [Control], key: Enter, action: ToggleInputProtection }
 - { mods: [Control], key: Enter, action: ToggleStatusLine }
 - { mods: [Control], key: Enter, action: ToggleTitleBar }
 - { mods: [Control], key: Enter, action: TraceBreakAtEmptyQueue }
 - { mods: [Control], key: Enter, action: TraceEnter }
 - { mods: [Control], key: Enter, action: TraceLeave }
 - { mods: [Control], key: Enter, action: TraceStep }
 - { mods: [Control], key: Enter, action: ViNormalMode }
 - { mods: [Control], key: Enter, action: WriteScreen, chars: '' }
 - { mods: [Control], key: Enter, action: CreateNewTab }
 - { mods: [Control], key: Enter, action: CloseTab }
 - { mods: [Control], key: Enter, action: MoveTabTo, position: 0 }
 - { mods: [Control], key: Enter, action: MoveTabToLeft }
 - { mods: [Control], key: Enter, action: MoveTabToRight }
 - { mods: [Control], key: Enter, action: SwitchToTab, position: 0 }
 - { mods: [Control], key: Enter, action: SwitchToPreviousTab }
 - { mods: [Control], key: Enter, action: SwitchToTabLeft }
 - { mods: [Control], key: Enter, action: SwitchToTabRight }
 - { mods: [Control], key: Enter, action: SetTabTitle }
 - { mods: [Control], key: Enter, action: SplitVertical }
 - { mods: [Control], key: Enter, action: SplitHorizontal }
 - { mods: [Control], key: Enter, action: ClosePane }
 - { mods: [Control], key: Enter, action: FocusPaneLeft }
 - { mods: [Control], key: Enter, action: FocusPaneRight }
 - { mods: [Control], key: Enter, action: FocusPaneUp }
 - { mods: [Control], key: Enter, action: FocusPaneDown }
 - { mods: [Control], key: Enter, action: SwapPaneLeft }
 - { mods: [Control], key: Enter, action: SwapPaneRight }
 - { mods: [Control], key: Enter, action: SwapPaneUp }
 - { mods: [Control], key: Enter, action: SwapPaneDown }
 - { mods: [Control], key: Enter, action: MovePaneLeft }
 - { mods: [Control], key: Enter, action: MovePaneRight }
 - { mods: [Control], key: Enter, action: MovePaneUp }
 - { mods: [Control], key: Enter, action: MovePaneDown }
 - { mods: [Control], key: Enter, action: ToggleSplitOrientation }
 - { mods: [Control], key: Enter, action: TogglePaneZoom }
 - { mods: [Control], key: Enter, action: ResizePane, direction: Right, percent: 5 }
 - { mods: [Control], key: Enter, action: LaunchLayout, name: '' }
 - { mods: [Control], key: Enter, action: SaveLayout }
 - { mods: [Control], key: Enter, action: OpenContextMenu }
 - { mods: [Control], key: Enter, action: SelectAll }
 - { mods: [Control], key: Enter, action: SoftReset }
 - { mods: [Control], key: Enter, action: CopyLastCommandPrompt }
 - { mods: [Control], key: Enter, action: CopyLastCommandOutput }
 - { mods: [Control], key: Enter, action: CopyLastCommandBlock }
 - { mods: [Control], key: Enter, action: CopyHyperlink }
 - { mods: [Control], key: Enter, action: SetTabColor }
 - { mods: [Control], key: Enter, action: ResetTabColor }
 - { mods: [Control], key: Enter, action: CloseAllTabs }
 - { mods: [Control], key: Enter, action: SetTabBarVisibility, mode: Always }
 - { mods: [Control], key: Enter, action: SetTabBarPosition, position: Top }
 - { mods: [Control], key: Enter, action: SpeakSelection }
 - { mods: [Control], key: Enter, action: StopSpeaking }