Profiles
All profiles inside configuration files share parent node profiles. To create profile you need to specify child node
profiles:
main:
#default configuration
profile_for_windows:
# windows specific entries
profile_for_macos:
# macos specific entries
Profile configuration
shell
configuration section allows you to specify the process to be started inside the terminal. It provides flexibility to override the default login shell and supports logging in to a remote host.
profiles:
profile_name:
shell: "/bin/bash"
arguments: ["some", "optional", "arguments", "for", "the", "shell"]
ssh
With this key, you can bypass local PTY and process execution and directly connect via TCP/IP to a remote SSH server.
profiles:
profile_name:
ssh:
host: remote-server.example.com
port: 22
user: "CustomUserName"
private_key: "path/to/key"
public_key: "path/to/key.pub"
known_hosts: "~/.ssh/known_hosts"
forward_agent: false
Note, only host option is required. Everything else is defaulted.
Keep in mind, that the user's ~/.ssh/config will be parsed with respect to the supported options above.
These values can be overridden in the local Contour configuration as follows:
ssh.host SSH server to establish the connection to.
ssh.port SSH port (defaults to 22). Only specify this value if it is deviating from the default value 22.
ssh.private_key Path to private key to use for key based authentication.
ssh.public_key Path to public key that belongs to the private key. When using key based authentication, it depends on the underlying backend, if the public key is also required. OpenSSL for example does not require it.
ssh.known_hosts Path to known_hosts file. This defaults to and usually is located in ~/.ssh/known_hosts.
ssh.forward_agent Boolean, indicating whether or not the local SSH auth agent should be requested to be forwarded. Note: this is currently not working due to an issue related to the underlying library being used, but is hopefully resolved soon.
Note, custom environment variables may be passed as well, when connecting to an SSH server using this builtin-feature. Mind, that the SSH server is not required to accept all environment variables.
If an OpenSSH server is used, have a look at the AcceptEnv configuration setting in the sshd_config
configuration file on the remote SSH server, to configure what environment variables are permitted to be sent.
escape_sandbox
option in the configuration file allows you to control the sandboxing behavior when the terminal is executed from within Flatpak. This configuration is relevant only if the terminal is running in a Flatpak environment.
copy_last_mark_range_offset
configuration option is an advanced setting that is useful when using the CopyPreviousMarkRange feature with multiline prompts. It allows you to specify an offset value that is added to the current cursor's line number minus 1 (i.e., the line above the current cursor).
copy_command_preserve_multiline
Set copy_command_preserve_multiline: true to preserve internal line breaks and tabs when using Copy Command. The default is false, which keeps single-line copying. CR/CRLF are normalized to LF; trailing whitespace is removed. Unsafe controls are filtered in both modes. Pasting multiline text into a destination without bracketed paste may execute commands immediately.
show_title_bar
configuration option determines whether or not the title bar will be shown when the terminal profile is activated.
On Linux, false (the default) is Contour's own header bar with the desktop's window buttons; with true the window manager draws the frame (KWin, Mutter, or a tiling WM's border or none), and the header bar keeps the tabs, new tab, search and menu: only the window buttons move out of it.
false, the header bar rounds the window's top corners while it is neither maximised nor full screen. Outside the corners the window is transparent, which takes a compositor: on X11 without one, the corners show black. Run a compositor there, or set show_title_bar: true.
window_shadow
configuration option sets how far the drop shadow around a frameless window reaches.
One of None, Small, Medium, Large or VeryLarge — the same names and sizes Breeze offers, so a Contour window matches the rest of a Plasma desktop.
show_title_bar set to true the window manager draws its own shadow along with its decoration, and no other Wayland compositor or X11 window manager offers a way for an undecorated window to publish one — so everywhere else, every value behaves as None. Windows and macOS draw a system shadow of their own instead.
dim_unfocused
configuration option dims a pane while it is not the focused one (an inactive pane of a split, or any pane of an unfocused window) by blending it toward its own background color. The value is the blend amount between 0.0 (dimming disabled; the classic default) and 1.0 (fully blended to the background). The native2026 default is 0.15.
size_indicator_on_resize
configuration option determines whether or not the size indicator will be shown when terminal will resized.
fullscreen
configuration option determines whether the terminal's screen should be put into fullscreen mode when the terminal profile is activated. Fullscreen mode expands the terminal window to occupy the entire screen, providing a distraction-free environment for your terminal sessions.
maximized
configuration option determines whether the terminal window should be maximized when the specified profile is activated. Maximizing a window expands it to fill the entire available space on the screen, excluding the taskbar or other system elements.
insert_after_yank
This configuration option determines whether the terminal should automatically switch from normal mode to insert mode after executing a yank command. When enabled, the terminal will enter insert mode, allowing for immediate text input. If disabled, the terminal will remain in normal mode, maintaining command functionality.
bell
Configuration section permits tuning the behavior of the terminal bell.
sound This option determines the sound ofBEL (also 0x07) to off or default or sound generated by a file located at path. alert This option determines whether or not a window alert will be raised each time a bell is ringed. Useful for tiling window managers like i3 or sway.
notify_on_command_finish
configuration tells you when a command you are not watching finishes: a desktop notification, the bell, or both.
profiles:
profile_name:
notify_on_command_finish:
when: unfocused
min_duration: 10
outcome: any
action: notify
clear_on: focus
✓ make finished, ✗ make failed (exit 2) or ✗ make killed (SIGSEGV), with how long it took, where it ran and the tab's name below. A newer finish in the same pane replaces the older notification, and clicking it brings the pane forward where the desktop reports clicks.
when never, unfocused (unless it is the focused pane of the active window), hidden (only while the pane is off screen: another tab is active, a sibling pane is zoomed, or the window is minimised) or always. min_duration Commands that ran for fewer seconds than this never notify.
outcome
any, or failure for commands that exited non-zero or died of a signal. action
notify (a desktop notification), bell (the profile's bell sound and window alert) or notify_bell (both). clear_on When a notification still on screen is withdrawn:
focus (the pane is focused), next (the pane's next command starts) or never. Only a desktop notification can be withdrawn, which is what Linux shows; on Windows and macOS the notice is a tray message, which stays until it times out whatever clear_on says. terminal_id
configuration option allows you to specify the terminal type that will be advertised by the terminal emulator. The terminal type indicates the set of capabilities and features that the terminal supports, enabling compatibility with different applications and systems.
pixel_reporting
Selects the unit Contour reports pixel sizes to applications in, via TIOCGWINSZ
(ws_xpixel/ws_ypixel), CSI 14 t, CSI 16 t and XTSMGRAPHICS.
Applications derive the cell size by dividing a reported extent by the grid and size image canvases from it, so on a scaled display this decides how large an image an application draws into a given area.
A report is only usable if that division is exact, and Contour's cell is the font's advance in device pixels — at a fractional scale it has no exact logical counterpart (17 / 1.75 = 9.714). Valid values (ignore-case):
Device— report device pixels. The division is exact, so an image lands 1:1 on the display's own pixels and is never resampled — gapless and sharp. The cost is that the application draws as many times more pixels per axis as the display is scaled by. This is the default.Logical— report logical pixels, matching the canvas size a terminal whose cell is integral in logical pixels (Konsole, for one) would report, which is useful when comparing the two on equal terms. Exact only where the scale divides both cell axes evenly (an unscaled display, or a 20x40 cell at scale 2). Otherwise each axis is floored on its own, which changes the cell's aspect ratio, and a full-page image is letterboxed by the difference — a few percent of unpainted space down one side.
On an unscaled display the two are identical.
frozen_modes
fmt formatted doc 0
smooth_line_scrolling
Defines the number of milliseconds to wait before actually executing the LF (linefeed) control code
in case DEC mode DECSCLM is enabled.
smooth_scrolling
Enables pixel-based smooth scrolling. When enabled, scrolling will be performed in pixel increments rather than jumping by full lines, providing a smoother visual experience similar to GNOME Terminal/VTE. This applies to mouse wheel and trackpad scrolling on the primary screen.
momentum_scrolling
Enables momentum (inertia) scrolling for touchpad gestures.
When enabled, lifting your finger from the touchpad after a swipe will cause
the terminal to continue scrolling with decelerating velocity, mimicking
the natural scrolling behaviour of macOS and iOS.
This governs touchpad finger-lift inertia only. Mouse-wheel smoothness is controlled by
smooth_scrolling, which glides discrete wheel notches with the same physics.
terminal_size
configuration option allows you to specify the initial size of the terminal window in terms of the number of columns and lines.
columns This option specifies the number of columns (characters) to be displayed in the terminal window. In the provided example, the value is set to 80.lines This option specifies the number of lines to be displayed in the terminal window. In the provided example, the value is set to 25.
margins
Enforces a horizontal and vertical margin to respect on both sides of the terminal. This is particularly useful on operating systems (like MacOS) that draw the border frame into the main widgets space, or simply to create some artificial space to improve the user's focus.
history
configuration allows you to customize the behavior and settings related to the terminal's history, including the number of preserved lines, auto-scrolling, and scroll events.
profiles:
profile_name:
history:
limit: 1000
hard_limit: 2000
auto_scroll_on_update: false
scroll_multiplier: 3
hard_limit The upper bound on the scrollback, and what makes eviction command-aware. Anything above
limit is headroom: the buffer is allowed to grow into it, and when it fills, whole (prompt, output) blocks are dropped from the top rather than a slice taken wherever limit fell. The oldest line kept is then a prompt with its command's output intact, instead of an orphaned tail. Block boundaries come from the OSC 133 marks a shell with shell integration emits, so with no such shell -- or for a single command whose output is larger than the whole headroom -- there is no boundary to honour and the buffer simply bounds at this value, evicting line by line as before. Values below limit are raised to it, which disables the feature; -1 means infinite, and an infinite limit makes this infinite too since nothing is ever evicted. Defaults to limit. auto_scroll_on_update This boolean option determines whether new output brings a view scrolled back into the history down to the bottom. Only output that adds lines counts: a prompt, a progress bar or a clock repainted in place does not, so a shell that redraws its prompt on a timer leaves the view where you put it. If set to false, the terminal maintains the current scroll position until you type, which always brings the view down. Defaults to false.
scroll_multiplier This option defines the number of lines to scroll when the ScrollUp or ScrollDown events occur. By default, scrolling up or down moves three lines at a time. You can adjust this value as needed. In the provided example, scroll_multiplier is set to 3.
scrollbar
configuration allows you to customize the appearance and behavior of the visual scrollbar in the terminal.
profiles:
profile_name:
scrollbar:
position: Right
mode: system
hide_in_alt_screen: true
marks: [failures, commands, running, user_marks, search_matches]
contour.yml written by an earlier version keeps Hidden, so set position: Right there to see the marks. Hidden turns the scrollbar, and with it the command marks, off. The scrollbar floats over the edge of the terminal, takes no column from it, and is shown only while there is history to scroll through. mode
system follows the operating system's scroll bar setting; overlay hides the bar at the bottom of the scrollback, unless a failed or running command or a user mark is above the view; always shows it while there is scrollback. Defaults to system; a configuration written before the 2026 defaults keeps always. Where the system publishes no setting, system means overlay. hide_in_alt_screen This boolean option determines whether the scrollbar should be hidden when the terminal is in the alternate screen mode. If set to true, the scrollbar will be hidden when the terminal switches to the alternate screen. If set to false, the scrollbar will remain visible even in the alternate screen mode.
marks Which marks the scrollbar shows as thin ticks; clicking a tick scrolls its line to the top of the view, opening it if it is folded. A list of
failures (commands that exited with an error), commands (every command that did not fail; running is listed on its own), running (commands still running, drawn as hollow ticks), user_marks (lines marked with mm in vi normal mode) and search_matches (the rows the active search matches, in yellow); [] shows none. The default is [failures, running, search_matches], or, in a configuration written before the 2026 defaults, [failures, commands, running, user_marks]. Command ticks need the OSC 133 marks a shell with shell integration emits -- or, without one, systemd's OSC 3008 contexts. Ticks are hidden whenever the scrollbar is. sticky_header
configuration pins the command line of the block you are reading over the top row of the terminal, once that command has scrolled out of view above its own output.
mode When the header appears:never, scrolled (only while the viewport is scrolled back into history; the default) or always (also while following live output, so a long build keeps its command in view). It needs prompt marks (OSC 133;A), never appears on the alternate screen, shows the command's exit status and duration on its right, and a click on it scrolls to the command. A shell that marks only where its commands run (;C, ;D) gets no header. show_evicted Whether the header still names a command whose own line has already been dropped from the scrollback, as
⋯ <command> — earlier output evicted, so a long output does not lose its header when its prompt is evicted. At the very top of the scrollback it shows whatever mode says (even never); anywhere else it shows wherever mode would show a header. mouse
configuration allows you to control the behavior of the mouse in the terminal.
hide_while_typing This boolean option determines whether the mouse cursor should be hidden while typing in the terminal. When set to true, the mouse cursor will be hidden when you start typing. When set to false, the mouse cursor will remain visible while typing.permissions
configuration allows you to control the access permissions for specific VT sequences in the terminal.
profiles:
profile_name:
permissions:
change_font: ask
capture_buffer: ask
display_host_writable_statusline: ask
OSC 50 ; Pt ST. The possible values are: allow, deny, ask. capture_buffer This option determines the access permission for capturing the screen buffer using the VT sequence
CSI > Pm ; Ps ; Pc ST. The response can be read from stdin as the sequence OSC 314 ; <screen capture> ST. The possible values are: allow, deny, ask.display_host_writable_statusline This option determines the access permission for displaying the "Host Writable Statusline" programmatically using the VT sequence
DECSSDT 2. The possible values are: allow, deny, ask. input_method_editor
fmt formatted doc true
input_method_editor_style
How text an input method is composing is drawn, at the cursor, or to its left when it would not fit.
Valid values are:
- inline - in the terminal's default colours with a thin underline, as it will read once committed
- highlighted - in the colour scheme's input_method_editor colours, bold and underlined
highlight_double_clicked_word
configuration option enables the highlighting of a word and its matches when double-clicked on the primary screen in the terminal.
change_font When this option is enabled (true), the following behavior occurs:- Double-clicking on a word in the primary screen will select and highlight the double-clicked word.
- Additionally, all other occurrences of the same word will also be highlighted without being selected.
- This feature is implemented by initiating a search for the double-clicked word.
- You can use the FocusNextSearchMatch and FocusPreviousSearchMatch actions to navigate to the next or previous occurrence of the same word, even if it is outside the current viewport.
fonts
section of the configuration allows you to customize the font settings for the terminal.
profiles:
profile_name:
font:
size: 12
locator: native
text_shaping:
engine: native
builtin_box_drawing: true
max_fallback_count: 16
render_mode: gray
strict_spacing: false
regular:
family: "monospace"
weight: regular
slant: normal
features: []
emoji: "emoji"
native2026 defaults. locator Determines the font locator engine to use for locating font files and font fallback. Possible values are
native and mock.native will use the operating-system native font location service (e.g. CoreText on macOS and DirectWrite on Windows), whereas mock is solely used for testing the software (not recommended by end-users)text_shaping.engine Selects the text shaping and font rendering engine. Supported values are native, DirectWrite, CoreText, and OpenShaper.
builtin_box_drawing Specifies whether to use built-in textures for pixel-perfect box drawing. If disabled, the font's provided box drawing characters will be used. The default value is true.
max_fallback_count Maximum number of fallback fonts per font style. Set to -1 for unlimited, 0 to disable fallbacks entirely. The default value is 16.
render_mode Specifies the font render mode, which tells the font rasterizer engine what rendering technique to use. Available modes are lcd, light, gray, color and monochrome.
strict_spacing Indicates whether only monospace fonts should be included in the font and font fallback list. The default value is false.
regular Defines the regular font style with the following parameters:
regular.family Specifies the font family name, such as "monospace", "Courier New", or "Fira Code".
regular.weight Specifies the font weight, such as thin, extra_light, light, demilight, book, normal, medium, demibold, bold, extra_bold, black, or extra_black.
regular.slant Specifies the font slant, which can be normal, italic, or oblique. regular.features Sets optional font features to be enabled. This is usually a 4-letter code, such as ss01 or ss02. Refer to your font's documentation for supported features. By default, no features are enabled.
emoji Specifies the font to be used for displaying Unicode symbols with emoji presentation. The default value is "emoji".
draw_bold_text_with_bright_colors
Specifies whether bold text should be rendered in bright colors for indexed colors. If disabled, normal colors will be used for bold text. The default value is false.
search_case_sensitivity
Which case policy the find bar opens with.
smart(default): the search is case-insensitive until the term contains an uppercase letter, at which point it becomes exact. Soerroralso findsError, whileErrorfinds only itself. The test is Unicode-aware, so it works for non-Latin scripts too.insensitive: never case-sensitive.sensitive: always case-sensitive.
The find bar's Aa button cycles the same three at any time; this only selects the one it starts from.
mouse_forwarding
Mouse Forwarding: whether mouse events reach an application that asks for them.
forwarded(default): an application that turns mouse tracking on (vim,tmux,htop, many TUIs) is told about clicks, motion and the wheel.blocked: no mouse report and no DEC locator event reaches the application, and a locator position request is answered as from an unavailable locator. Selecting, scrolling and following links work as if no application had asked, and on the alternate screen the wheel still becomes cursor keys (alternate scroll). The application's request is still recorded, so forwarding again resumes the protocol it asked for.
The ToggleMouseForwarding action flips this at runtime. A profile switch or a configuration reload re-imposes the profile's value.
blink_style
Determines the visual style of cell blink animation (SGR attributes 5 and 6).
Valid values are:
- classic - abrupt on/off toggle
- smooth - continuous cosine-based pulse
- linger - like smooth but stays visible longer
screen_transition_style
Determines the visual style of screen transitions between primary and alternate screens.
When switching between primary and alternate screen buffers (e.g. entering/leaving vim, htop), this setting controls whether the transition is instant or animated.
Valid values are:
- classic - instant switch (no animation)
- fade - smooth fade-out/fade-in (250ms by default; 150ms under the native2026 defaults)
screen_transition_duration
Duration in milliseconds for the screen transition animation.
Only applies when screen_transition is set to fade.
cursor_motion_animation_duration
Duration in milliseconds for the cursor motion animation when the cursor moves between cells.
Set to 0 to disable cursor motion animation (instant jumps).
mode_insert
section of the configuration allows you to customize the appearance and behavior of the terminal cursor.
shape Specifies the shape of the cursor. You can choose from the following options:-block: A filled rectangle.
-rectangle: Just the outline of a block.
-underscore: A line under the text.
-bar: The well-known i-Beam cursor.
blinking Determines whether the cursor should blink over time. If set to true, the cursor will blink; if set to false, the cursor will remain static.
blinking_interval Specifies the blinking interval in milliseconds. This value defines how quickly the cursor alternates between being visible and invisible when blinking is enabled.
mode_normal
section in the configuration allows you to customize the appearance and behavior of the cursor specifically in vi-like normal mode.
mode_visual
section in the configuration allows you to customize the appearance and behavior of the cursor specifically in vi-like normal mode.
highlight_timeout
option in the configuration determines the duration in milliseconds for which the yank highlight is shown in vi mode. After yanking (copying) text in vi mode, the yanked text is typically highlighted momentarily to provide visual feedback. This configuration option allows you to specify the duration of this highlight.
modal_cursor_scroll_off
option in the configuration sets the scrolloff value for cursor movements in normal and visual (block) modes. The scrolloff value determines the minimum number of lines to keep visible above and below the cursor when scrolling. In other words, it controls the amount of margin or padding around the cursor during scrolling operations.
status_line
section in the configuration file allows you to customize the behavior and appearance of the status line in the terminal.
display specifies whether the status line should be shown or not. The possible values are none (status line is not shown) and indicator (status line is shown). In the example, the status line is set to none, meaning it will not be displayed initially.position determines the placement of the status line. It can be set to top or bottom. In the example, the status line is set to bottom, indicating that it will appear at the bottom of the terminal window if enabled.
sync_to_window_title controls whether the window title should be synchronized with the Host Writable status line. If the Host Writable status line is denied, enabling this option will update the window title accordingly. By default, this option is set to false.
extension names an entry of the profile's
extensions section that takes the whole status line over. By default it is null, which keeps the template-driven status line. extensions
section in the configuration file declares the WebAssembly extensions that may draw into the status line of a profile. None is configured by default.
profiles:
profile_name:
extensions:
git: { run_command: ask }
plasma: { config: { speed: "2" } }
mine: { path: ~/wasm/mine.wasm, run_command: deny }
status_line:
extension: plasma
indicator:
right: "{Extension:git} | {Clock:Bold}"
~ is the home directory. Without it, the entry's name selects an extension bundled with Contour. config holds text values the extension reads by key.
run_command decides whether the extension may run the commands its manifest declares:
allow, deny or ask. The default is ask. An extension is used by naming it in a status line template as {Extension:name}, or, with status_line.extension, by letting it take the whole line over.
background
section in the configuration file allows you to customize the background settings for the terminal.
opacity specifies the background opacity to use. The value ranges from 0.0 to 1.0, where 0.0 represents fully transparent and 1.0 represents fully opaque. You can adjust this value to control the transparency level of the terminal's background.blur determines whether the transparent background should be blurred on platforms that support it. Currently, only Windows 10 is supported for background blurring. By default, this option is set to false, meaning no background blurring will be applied.
colors
section in the configuration file allows you to specify the colorscheme to use for the terminal. You can use one of the predefined color palettes as a setting for colors entry.
List of predefined colorschemes: contour(default colors), monokai, one-light, one-dark, gruvbox-light, gruvbox-dark, solarized-light, solarized-dark, papercolor-light, papercolor-dark.
Under defaults_edition: native2026, colors: default (the stock scheme, unmodified) means the pair contour-dark/contour-light, so the terminal follows the system's dark mode; naming another scheme keeps it fixed, and classic keeps default as one fixed scheme.
To make the terminal's color scheme dependant on OS appearance (dark and light mode) settings, you need to specify two color schemes:
With this, the terminal will use the color scheme as specified in dark when OS dark mode is on,
and light's color scheme otherwise.
A configuration reload applies the colors to running sessions too, replacing any a program set there (OSC 4, 10, 11 and friends), just as switching to another profile does.
hyperlink_decoration
section in the configuration file allows you to configure the styling and colorization of hyperlinks when they are displayed in the terminal and when they are hovered over by the cursor.
Possible values: underline, dotted-underline, double-underline, curly-underline, dashed-underline, overline, crossed-out, framed, encircle (if implemented)
profiles:
profile_name:
hyperlink_decoration:
mode: always
normal: dotted-underline
hover: underline
mode when links are decorated: always, hover (only the one under the pointer), modifier (all of them while the follow modifier is held), never.
link_detection
section decides which links are found automatically in printed text, per screen. OSC 8 hyperlinks are always links, and hint mode always offers everything.
primary_screen is the normal shell screen; other_screens is the alternate screen (vim, less, htop, ...) and every further page.
urls also covers your own patterns, unless they open a file: URL, which follows file_paths.
profiles:
profile_name:
link_detection:
primary_screen:
urls: true
file_paths: true
other_screens:
urls: true
file_paths: false
file_opener
opens detected file paths on Ctrl+click and with hint mode's Open.
command is a command line with {path}, {line} and {column}, split into arguments
once, with no shell involved; its program is written out, without a placeholder.
placement is detached (default), split or tab.
Without a command, a file opens with the system's default application; a directory always opens in the
file manager.
profiles:
profile_name:
file_opener:
command: 'code --goto {path}:{line}:{column}'
placement: detached
hint_patterns
fmt formatted doc {}
hint_scrollback_lines
fmt formatted doc 1000
wm_class
Configuration option defines the class part of the WM_CLASS property of the terminal window. The WM_CLASS property is a standard X11 property used to identify and classify windows by their class and instance.
tab_label
Default template for the text shown on each GUI tab. The value is a string with optional {Name} placeholders that are substituted per tab:
{TabName}— the tab name the application set with OSC 30, as the indicator status line shows it, or the window title when the application set none (or cleared it). This is the default.{WindowTitle}— the active pane's window title (OSC 0/2), ignoring any tab name.{TabPosition}— the tab's 1-based position in the window.
Literal text outside placeholders is kept verbatim, and an unknown placeholder is echoed verbatim (you see exactly the {Name} you typed). Renaming a tab overrides this default for that tab; the rename text may itself contain the same placeholders (so renaming a tab to {WindowTitle} tracks its title). A tab holding a split is shown as Multiple panes.
tab_color
Default tab color as '#RRGGBB', or null for no profile color. Layout, user and application colors override it. Split tabs keep the color of the profile that created the tab.
option_as_alt
section tells Contour which Option keys act as Alt (Meta) on macOS: off, left, right or both.
The other Option key keeps typing accents like é and ü. true and false are still read, as both and off.
This value is ignored on other platforms.