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 wether 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).
show_title_bar
configuration option determines whether or not the title bar will be shown when the terminal profile is activated.
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.
search_mode_switch
The configuration option determines whether the editor should automatically switch from search mode back to insert mode upon exiting a search. If enabled, the terminal will return to insert mode, allowing for immediate text input. If disabled, the terminal will remain in normal mode.
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.
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.
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.
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 particularily 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.
limit This option specifies the number of lines to preserve in the terminal's history. A value of -1 indicates unlimited history, meaning that all lines are preserved. In the provided example, the limit is set to 1000.auto_scroll_on_update This boolean option determines whether the terminal automatically scrolls down to the bottom when new content is added. If set to true, the terminal will scroll down on screen updates. If set to false, the terminal will maintain the current scroll position. In the provided example, auto_scroll_on_update is set to true.
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.
position This option specifies the position of the scrollbar in the terminal window. It can be set to one of the following values: Left, Right, Hidden.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.
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. 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
dpi_scale: 1.0
locator: native
text_shaping:
engine: native
builtin_box_drawing: true
render_mode: gray
strict_spacing: true
regular:
family: "monospace"
weight: regular
slant: normal
features: []
emoji: "emoji"
dpi_scale Allows applying a DPI scaling factor on top of the system's configured DPI. The default value is 1.0.
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.
render_mode Specifies the font render mode, which tells the font rasterizer engine what rendering technique to use. Available modes are lcd, light, gray, and monochrome.
strict_spacing Indicates whether only monospace fonts should be included in the font and font fallback list. The default value is true.
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.
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.
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.
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.
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)
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.
option_key_as_alt
section tells Contour how to handle Option-Key events on MacOS. This value is ignored on other platforms.