Configuration reference
This page is generated from the configuration file Ubiquitty writes on first run, which the product treats as the reference for what can be set. Each key is shown at its built-in default; uncomment it in your file to change it. The type column comes from the parser’s own key tables.
Generated from product version 0.2.0, commit c989e6125e.
The file
Section titled “The file”The file is ~/.config/ubiquitty/config.toml. The Settings window writes to the same file, so the two are interchangeable. Configuration says when each platform applies a change.
Sections
Section titled “Sections”[font][[font.language_fallbacks]][[font.range_map]][underline][text][appearance][[tags]][[tags]][[tags]][cursor][render][tek][bell][sound][selection][links][link_handlers][paste][clipboard][mouse][tabs][window][title][quake][dock][security][capabilities.local][capabilities.agent][capabilities.remote][control][notifications][network][remote][transfer][term][terminal][unicode][keys][macros][triggers][scripting][experimental][debug][[themes]][[profiles]][mac][mac.keys][linux]
[font]
| Key | Default | Type | Description |
|---|---|---|---|
family |
"SF Mono" |
string | default when installed; otherwise bundled JetBrains Mono |
fallback |
"" |
string | existing symbol fallback alias; empty uses built-in defaults |
size |
12 |
number | points, fractions included: 12.5 is a size |
proportional_family |
"" |
string | face for proportional runs (OSC 66 p=1); empty uses the system UI face |
proportional_size |
0 |
number | points for proportional runs, fractions included; 0 sets them one optical step over the grid size |
baseline_offset |
0 |
number | points the glyphs shift within the cell, + up. For a face that sits low or high in its own metrics |
ligatures |
true |
boolean | programming ligatures (calt) |
features |
"calt liga -dlig ss01" |
string | OpenType feature allow/block: bare/+tag on, -tag off (zero, dlig, calt, ss01-ss20) |
variations |
"slnt=-6 opsz=14" |
string | variable-font axes, tag=value; a tag here beats font.weight/font.width |
symbol_fallback |
"" |
string | empty uses bundled Symbols Nerd Font Mono |
emoji_fallback |
"auto" |
string | auto | system | installed emoji font family |
cjk_fallback |
"auto" |
string | auto | zh-Hans | zh-Hant | ja | ko | installed CJK font family |
line_spacing |
2 |
number | extra points added between rows, fractions included |
match_fallback_size |
true |
boolean | match system fallback text to the primary font |
wide_glyph_boost |
true |
boolean | optically scale CJK/Hangul/fullwidth mono glyphs inside their two-cell slot |
braille_grid |
true |
boolean | draw braille as a 2x4 dot lattice on an even pitch; false takes the font’s glyphs |
braille_style |
"regular" |
string | regular | outline-6 | outline-8 | pinpoint-6 | pinpoint-8 | square | raster |
character_spacing |
0 |
number | pt added to each cell’s width, negative to tighten. A CoreText face is tracked by the exact value and keeps the gap after the glyph; the GNU Unifont bitmap face and the Linux FreeType grid round it to whole backing pixels, and the bitmap cell splits its gap around the glyph |
weight |
400 |
integer | ‘wght’ axis for upright text; omit for the face’s own |
bold_weight |
700 |
integer | ‘wght’ axis for bold text; omit for the face’s own |
width |
112.5 |
number | width percent for faces with a width axis or members; omit for the face’s own |
wide_glyph_scale |
1.2 |
number | multiplier for wide glyph ink |
[[font.language_fallbacks]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
[[font.language_fallbacks]]script = "han" # han | kana | hangul | arabic | ...language = "ja" # BCP-47-style token or * for script defaultmode = "custom" # auto | system | regional | customfamily = "Hiragino Sans"[[font.range_map]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
A range routes code points the primary font lacks to a family. Yours come first; after them, the media controls (U+23E9-U+23FA), Geometric Shapes (U+25A0-U+25FF) and the large shapes (U+2B12-U+2B2F) go to the bundled Monaspace Neon, so circles and squares a font lacks match.
[[font.range_map]]range = "U+4E00-U+9FFF"mode = "custom"family = "Hiragino Sans"[underline]
| Key | Default | Type | Description |
|---|---|---|---|
thickness |
1.0 |
number | multiplier on the font’s underline weight |
offset |
0 |
number | extra points below the baseline (+down) |
skip_ink |
true |
boolean | descenders break the underline rule |
follows_ink |
true |
boolean | a word’s outer rule reaches the letter’s ink past the cell |
skip_ink_pad |
1.75 |
number | clean-gap halo radius around ink, points |
links |
true |
boolean | OSC 8 link cells get an underline |
link_style |
0 |
integer | link underline: 0 = solid (default), 1 = dotted |
link_color_blue |
false |
boolean | force link text + underline to system blue (web-style) |
link_style_per_kind |
false |
boolean | off (default): all links use link_style; on: OSC 8 kinds distinct (file:// dotted, mailto: dashed, url/other base) |
[text]
| Key | Default | Type | Description |
|---|---|---|---|
brighten_bold |
false |
boolean | bold text promotes ANSI fg 0..7 to bright 8..15 |
[appearance]
Padding defaults: 6 left, right and bottom and 0 top on a desktop; 4 on every edge on iOS, inside the screen’s safe area.
| Key | Default | Type | Description |
|---|---|---|---|
theme |
"Ayu Mirage" |
string | theme name (default: “Noir”) |
color_space |
"display-p3" |
string | srgb | display-p3 |
beam_terminal_font |
false |
boolean | Beam renders in the terminal’s font, not the system font |
padding |
6 |
number | inner window padding, points (0..64); shorthand for all four edges |
padding_left |
6 |
number | left inset, points (0..64); overrides padding |
padding_right |
6 |
number | right inset, points (0..64); overrides padding |
padding_top |
0 |
number | top inset, points (0..64); overrides padding |
padding_bottom |
6 |
number | bottom inset, points (0..64); overrides padding |
titleless_top_padding |
6 |
number | top inset in chromeless (hide_title_bar) mode, points (0..64); default = padding_bottom |
square_bottom_corners |
true |
boolean | square off the window’s bottom corners (top stays rounded) |
titlebar_style |
"themed" |
string | title bar look: “themed” (matches terminal background) | “native” (system vibrant) |
beam_surface |
"auto" |
string | command palette: “auto” | “native” (frontend UI) | “in-terminal” (drawn in the cell grid) |
folder_icon |
true |
boolean | show the current-directory folder proxy icon in the title bar |
folder_icon_always |
false |
boolean | keep that icon shown instead of revealing it on hover |
pane_title_bars |
true |
boolean | show a title bar on each pane in split layouts |
blink_animation |
true |
boolean | cursor/text blink fades smoothly; false = hard on/off blink |
snap_window_resize |
true |
boolean | resize in whole-cell steps, except flush to a screen edge / dock (default: off) |
hide_title_bar |
false |
boolean | hide the title bar + traffic lights (keeps rounded corners); Cmd-drag the body to move |
colorblind_mode |
"none" |
string | CVD-safe palette remap: none | deuteranopia | protanopia | tritanopia |
shade_blocks |
"pattern" |
string | shades: “pattern” (solid pixels, a quarter/half/three quarters lit) | “fill” (translucent tint) |
ui_font_scale |
1.0 |
number | chrome (tabs/HUD/settings) font multiplier (0.5..2.0); independent of the grid font |
tag_color_opacity |
0.5 |
number | how strongly tag colours are drawn in the title bar and on tabs (0.1..1.0) |
follow_system |
true |
boolean | auto-switch theme to match the system dark/light mode (default: on) |
system_dark_theme |
"Noir" |
theme name for dark mode when follow_system is on | |
system_light_theme |
"Noir Clair" |
theme name for light mode when follow_system is on | |
background_opacity |
1.0 |
number | window background alpha (0..1); <1 lets the desktop show through behind text |
text_contrast |
false |
boolean | improve faint text against each cell background without changing its hue |
text_contrast_on_blur |
false |
boolean | blend text with the native blurred material |
background_vibrancy |
true |
boolean | blend explicit cell backgrounds with the native material below full opacity |
blur_radius |
20.0 |
number | gaussian blur radius in points (0..50); > 0 enables the behind-window blur |
background_image |
"" |
string | path to an image painted behind the grid (PNG/JPEG); empty = none |
background_image_opacity |
1.0 |
number | image alpha (0..1) when composited behind the grid; needs background_opacity < 1 |
default_background_opacity |
1.0 |
number | alpha (0..1) for DEFAULT-background cells only; < 1 keeps SGR-colored cells solid while empty space shows through |
background_image_mode |
"fill" |
string | fill | fit | stretch | tile | center |
[[tags]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
Window tags — a named, coloured marker a window wears so what it is connected to is legible before it is read. match_host and match_profile are globs; an entry with neither marks nothing on its own, and only names a colour for a tag set by hand or by the session. Colours: red, orange, yellow, green, blue, purple, gray, or a #rrggbb literal. match_host reads the machine the title row’s host chip names, however the window got there: a ubiquitty-host over ssh or QUIC, this machine’s own daemon (by this machine’s name), a typed ssh, or tmux control mode. A host saved under a label matches by either name. A machine known by several names (its own hostname, a tailnet name) takes an array of patterns, any of which matches. The tab wears the first tag’s colour at its leading edge. name is optional: a rule with a colour and no name is drawn as a dot of that colour. icon names a Phosphor icon (database, cloud, flame, lock, …) drawn in the tag’s colour in place of the dot on the tab and the globe beside the host; icon_weight is fill (default) or regular.
[[tags]]name = "production"color = "red"match_host = "prod-*"icon = "flame"[[tags]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
[[tags]]name = "studio"color = "purple"match_host = ["studio-mac*", "studio.tailnet.example"]icon = "desktop-tower"icon_weight = "regular"[[tags]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
[[tags]]color = "blue"match_host = "home-*"[cursor]
| Key | Default | Type | Description |
|---|---|---|---|
shape |
"block" |
string | block | underline | bar |
blink |
true |
boolean | |
linger |
40 |
integer | frames the cursor stays solid after a keystroke (40 short / 70 long) |
blink_rate |
1000 |
integer | blink period in milliseconds, one full on/off cycle (lower = faster) |
alpha |
255 |
integer | 0..255, cursor color alpha (255 = opaque) |
invert_text |
false |
boolean | block cursor sits behind the glyph; true tints that glyph to the grayscale inversion of the cursor color |
motion |
"off" |
string | caret glide by distance: off | short (small moves) | long (jumps) | always; Reduce Motion snaps |
motion_duration |
110 |
integer | ms for the caret to reach its target cell when motion glides (1..1000) |
[render]
| Key | Default | Type | Description |
|---|---|---|---|
max_fps |
0 |
integer | cap the continuous-output frame rate (0 = uncapped / panel native rate) |
vsync |
true |
boolean | tear-free present via the display link; false presents frames as soon as ready |
[tek]
| Key | Default | Type | Description |
|---|---|---|---|
bright_pen |
false |
boolean | storage-tube bright spot at the writing beam |
glow_vectors |
false |
boolean | additive bloom on all Tek vectors (lit-CRT look) |
color_mode |
0 |
integer | 0 = follow the terminal theme, 1 = the custom colors below |
beam_color |
"#33ff66" |
string | custom-mode beam color (green phosphor) |
background_color |
"#0a0a0a" |
string | custom-mode background (near-black) |
[bell]
| Key | Default | Type | Description |
|---|---|---|---|
audible |
true |
boolean | |
visual |
false |
boolean | |
visual_intensity |
0.35 |
number | peak opacity of the visual-bell flash (0.05..1.0; 0.35 = default) |
[sound]
DECPS play-sound: the synth a program drives with CSI … , ~ — voices, eight channels, and samples it downloads. Not the bell above.
| Key | Default | Type | Description |
|---|---|---|---|
audible |
true |
boolean | false silences it; a program can ask and show something visible instead |
volume |
1.0 |
number | master level for everything a program plays (0.0..1.0) |
[selection]
| Key | Default | Type | Description |
|---|---|---|---|
copy_on_select |
false |
boolean | copy to the pasteboard on select |
select_modifier |
"shift" |
string | shift, cmd, ctrl: select through mouse-reporting apps |
block_select_modifier |
"opt" |
string | the chord that makes a drag rectangular: opt, shift+opt, cmd+opt or ctrl+opt, matched exactly. ctrl+opt takes over the macOS Control-click contextual menu. Shift-drag reaches a run of text through a mouse-tracking app, and the block chord above reaches a rectangle the same way. Shift is xterm’s own override and is not configurable. |
style |
"native" |
string | native: the system selection colour under the text; tint: a translucent tint over it. Where the system names no colour, native draws the tint. |
smart_double_click |
false |
boolean | double-click selects a URL/path token, not a word |
restrict_to_text |
false |
boolean | pointer is a text cursor over text and an arrow over blank space. Pointer shape only — what a drag selects is unchanged. |
links_override_reporting |
true |
boolean | a plain click opens a link even while an app is using the mouse. Off gives every click to the app, and Cmd still opens the link. |
copy_style |
"everything" |
string | what Cmd-C carries: everything | no-background | styles-only | plain (plain text, no styling) |
copy_style_theme |
"" |
string | render the styled copy in a named theme instead of the current one; empty or “default” uses the current |
osc8_click_opens |
true |
boolean | a plain click opens an OSC 8 link, on macOS and Linux alike. A regex-guessed link needs Cmd/Ctrl — the program never said that text was a URL — and so does an ssh, sftp, ftp or ftps link, which connects to a host the program named. On iPhone and iPad a tap is the click, and never opens one of those: touch and hold it and choose Open Link. The scheme allowlist (http/https/file/mailto/ftp/ftps/ssh/sftp) applies either way; this only decides the click. |
[links]
| Key | Default | Type | Description |
|---|---|---|---|
line_handler |
"" |
string | the program a file link that names a line opens in: #L12, #L12-L20 or #L12:5, with or without the L, as rg –hyperlink-format and delta write them. Words split on spaces, and no shell runs it; {path}, {line} and {column} are filled in wherever they stand, with the file the click checked rather than the link as printed, and a column of 1 when the link names none. Empty: such a link opens as any file link does. Examples, each one string: code –goto {path}:{line}:{column} zed {path}:{line}:{column} wezterm start – nvim +{line} {path} A program named without a path is found on the app’s PATH, which for an app the Dock starts is the system’s. Name an editor: any file goes to it, a script included, so open or xdg-open here would run one. No quoting: name a program whose path has a space through a symbolic link without one. |
[link_handlers]
Not set in the default file. The block below is the default file’s example.
Link handlers — a URL scheme mapped to the command that opens it, consulted before the rules a link meets with none, a file link’s included. A link whose target hides part of itself (a control, a direction override, a zero-width space) is refused first. %s (or %u) is the link as the program printed it, one argument; a command naming neither gets it appended. No shell runs it. macOS only.
[link_handlers]jira = "open -a Jira %s"[paste]
| Key | Default | Type | Description |
|---|---|---|---|
confirm_multiline |
true |
boolean | prompt before pasting clipboard text that spans multiple lines (safety guard) |
confirm_multiline_threshold |
1 |
integer | only confirm when the paste exceeds this many lines (1 = confirm on > 1 line) |
[clipboard]
| Key | Default | Type | Description |
|---|---|---|---|
remote_tools |
"off" |
string | which pasteboard PROGRAMS on a remote host read: off (the host has none, so they find nothing) or client (shims for xclip, wl-paste and pbpaste go on the session PATH and answer from this machine’s pasteboard). Off by default: a shim exposes your pasteboard to every process on that host that runs xclip. |
[mouse]
| Key | Default | Type | Description |
|---|---|---|---|
wheel_speed |
1.0 |
number | MOUSE WHEEL speed multiplier (0.1..10.0; 1.0 = default) |
wheel_lines |
1 |
integer | base lines a wheel notch scrolls before the multiplier (1..20) |
trackpad_speed |
1.0 |
number | TRACKPAD speed multiplier (0.1..4.0; independent of wheel_speed) |
scroll_bounce |
true |
boolean | Elastic scrolling at scrollback edges (macOS modern renderer) |
[tabs]
| Key | Default | Type | Description |
|---|---|---|---|
show_shortcuts |
"always" |
string | ⌘N hint on each tab: “off” | “always” | “command” (only while ⌘ held) |
[window]
| Key | Default | Type | Description |
|---|---|---|---|
initial_columns |
220 |
integer | pin the first window to this column count (10..1000); 0 = use saved frame |
initial_rows |
50 |
integer | pin the first window to this row count (4..500); 0 = use saved frame |
drag_modifier |
"control+command" |
string | modifier to drag the window from anywhere in the grid; empty / “none” = title-bar drag only |
program_fullscreen |
"fill" |
string | how a program’s CSI 10 t goes full screen: fill | native. fill = resize over the visible frame (stays resizable); native = the macOS transition (own Space, cannot resize). The green button is always native. |
[title]
What each title surface weaves in. Every flag below is on unless it says otherwise, and the values shown are the built-in defaults.
The pane flags carry no value here: an unset one inherits the RESOLVED tab flag rather than a default of its own, so pane_directory = true would name a default the pane does not have. Set any to override what it inherits: pane_directory, pane_directory_path, pane_app_title, pane_process, pane_process_arguments, pane_shell_command, pane_tty_name, pane_profile_name, pane_program_status, pane_text. pane_dimensions inherits nothing and is off until set.
| Key | Default | Type | Description |
|---|---|---|---|
window_directory |
true |
boolean | the working directory |
window_directory_path |
false |
boolean | false = folder name (“user”), true = full tilde path |
window_app_title |
true |
boolean | the title a program set with OSC 0/1/2 |
window_process |
true |
boolean | the foreground process chain |
window_process_arguments |
false |
boolean | the chain leaf’s full argv |
window_shell_command |
false |
boolean | the session-leader shell’s name |
window_tty_name |
false |
boolean | the replica tty basename (“ttys003”) |
window_profile_name |
false |
boolean | the applied profile’s name |
window_text |
"" |
string | static text leading the weave; empty = absent |
window_dimensions |
true |
boolean | the column x row count |
window_program_status |
true |
boolean | the label a program gives its status (“Waiting”) |
tab_directory |
true |
boolean | |
tab_directory_path |
true |
boolean | tabs show the tilde path where windows show the name |
tab_app_title |
true |
boolean | |
tab_process |
true |
boolean | |
tab_process_arguments |
false |
boolean | |
tab_shell_command |
false |
boolean | |
tab_tty_name |
false |
boolean | |
tab_profile_name |
false |
boolean | |
tab_text |
"" |
string | |
tab_dimensions |
false |
boolean | the tab strip has never shown dimensions |
tab_program_status |
false |
boolean | off: a label that changes as the program works re-lays out the strip |
[quake]
| Key | Default | Type | Description |
|---|---|---|---|
enabled |
false |
boolean | drop-down terminal; gates the feature and its global hotkey. The rest of this section only matters when it is on. |
hotkey |
"control+grave" |
string | toggle spec that drops the window down and hides it again |
height |
0.5 |
number | fraction of the screen height it covers (0.2..1.0) |
animate |
true |
boolean | slide it down from the top edge; false places it at once |
[dock]
| Key | Default | Type | Description |
|---|---|---|---|
bounce |
true |
boolean | bounce the Dock icon on a background bell/notification |
badge |
true |
boolean | show a Dock badge count of missed attention events |
[security]
| Key | Default | Type | Description |
|---|---|---|---|
secure_keyboard_entry |
true |
boolean | block other apps from reading keystrokes while focused |
password_detect |
true |
boolean | mask local echo + show a lock when a password prompt is detected |
secure_keyboard_entry_at_password_prompts |
true |
boolean | hold Secure Keyboard Entry while a pane is at a password prompt |
clipboard_read |
"prompt" |
string | OSC 52 clipboard-read gate: prompt | allow | deny |
clipboard_write |
"allow" |
string | OSC 52 clipboard-write gate: allow | deny |
osc_allow |
"" |
string | if set, only these OSC codes run (e.g. “0 8 52”); deny still wins |
osc_deny |
"" |
string | block these OSC codes (decimal, e.g. “52 1337”) |
dcs_allow |
"" |
string | if set, only these DCS kinds run: sixel decudk decrqss xtgettcap tmux |
dcs_deny |
"" |
string | block these DCS kinds (e.g. “sixel”) |
apc_allow |
"" |
string | if set, only APCs starting with these bytes run (G = kitty graphics) |
apc_deny |
"" |
string | block APCs by first byte (e.g. “G” turns kitty graphics off) |
[capabilities.local]
What a program in a host session may do without asking, by who drives it: local (this machine), agent (a local automation client) or remote (your own device attached over SSH or QUIC). Each key is allow | prompt | deny. Read by the host daemon when it starts. Feature queries and image rendering are always allowed and have no key.
| Key | Default | Type | Description |
|---|---|---|---|
informational |
"allow" |
hyperlinks, cursor shape, colours, fonts, cwd / host / file notes | |
host_escaping |
"allow" |
clipboard writes, notifications, sound, window moves, triggers, file reads | |
read_exfiltration |
"allow" |
screen-content checksums, window-title and clipboard reads |
[capabilities.agent]
| Key | Default | Type | Description |
|---|---|---|---|
informational |
"allow" |
||
host_escaping |
"prompt" |
||
read_exfiltration |
"prompt" |
[capabilities.remote]
Unset, host_escaping asks before clipboard writes and notifications and denies the rest; set, the one verdict covers all of it, so “deny” stops the asking too.
| Key | Default | Type | Description |
|---|---|---|---|
informational |
"allow" |
prompt or deny to stop a remote program restyling the screen | |
host_escaping |
"deny" |
||
read_exfiltration |
"deny" |
[control]
A local JSON-RPC socket for scripting the app. Off unless enabled, never synced, owner-only, and uid-checked on every connection. The reference is https://github.com/yaglo/ubiquitty/blob/main/Docs/control-socket.md
| Key | Default | Type | Description |
|---|---|---|---|
enable |
false |
boolean | bind the socket at launch |
socket_path |
"" |
string | override the default ~/.ubiquitty/control.sock |
token |
"" |
string | optional shared secret a caller must present |
approve |
false |
boolean | a confirm verdict from the agent policy counts as approved (the CLI’s –yes) |
[notifications]
| Key | Default | Type | Description |
|---|---|---|---|
enabled |
true |
boolean | post OS notifications for OSC 9/99/777 + unfocused bells |
sound |
true |
boolean | play the default banner sound with each notification |
[network]
| Key | Default | Type | Description |
|---|---|---|---|
proxy_kind |
"none" |
string | SOCKS/HTTP proxy for native ssh/mosh: none | socks5 | socks4 | http |
proxy_host |
"" |
string | proxy host (used as ssh ProxyCommand nc -X <kind> -x host:port) |
proxy_port |
0 |
integer | proxy port (1..65535; 0 = off) |
ssh_forward_agent |
false |
boolean | default ssh -A on a new SSH/mosh session (forward the auth agent) |
[remote]
| Key | Default | Type | Description |
|---|---|---|---|
auto_install_host |
true |
boolean | deploy the host helper to a remote that has none |
history_cache_on_disk |
false |
boolean | opt in to encrypted remote history; clear/disable retires it |
non_owner_presentation |
"letterbox" |
string | “pan” follows the cursor; “fit” scales to the existing font-size floor |
[transfer]
| Key | Default | Type | Description |
|---|---|---|---|
download_dir |
"" |
string | where ZMODEM-received (rz/sz) files are saved; empty = ~/Downloads. The save location is always confirmed before any file is written. |
auto_receive |
true |
boolean | auto-run the receiver on a detected ZMODEM send (still confirmed) |
zmodem |
true |
boolean | watch host output for a ZMODEM handshake |
[term]
| Key | Default | Type | Description |
|---|---|---|---|
program |
"Ubiquitty" |
string | TERM_PROGRAM |
version |
"" |
string | TERM_PROGRAM_VERSION |
identifier |
"xterm-256color" |
string | $TERM; default: xterm-ubiquitty (auto-installed) or xterm-256color |
set_locale_environment |
true |
boolean | set LANG/LC_* to match the system Off leaves them to your shell rc — LANG carries LC_NUMERIC, and a moved decimal separator has broken build scripts |
[terminal]
| Key | Default | Type | Description |
|---|---|---|---|
close_confirmation |
"running" |
string | always | never | running |
close_ignored_processes |
"screen, tmux, less, more, view, mandoc, tail, log, top, htop" |
string | |
emulation |
"vt" |
string | escape grammar the parser interprets: vt (default, DEC/ANSI) | linux | sco layer console sequences on the ANSI path; wyse | televideo | adm | heath | hp are non-ANSI legacy grammars |
encoding |
"utf-8" |
string | input charset: utf-8 (default) | latin1 | iso-8859-15 | koi8-r | windows-1252 | shift_jis | euc-jp | euc-kr | gb18030 | big5 — legacy bytes are decoded to Unicode before the grapheme stage; unknown names keep utf-8 |
invalid_utf8 |
"fffd" |
string | substitution for invalid/truncated UTF-8: fffd (default, U+FFFD) | drop (emit nothing) | latin1 (each bad byte as ISO-8859-1) |
scrollback_lines |
10000 |
integer | lines of history each session retains; applies to new sessions (default 10000) |
column_mode_resizes_window |
true |
boolean | DECCOLM (80/132) resizes the window (xterm c132); false renders in place. Fullscreen always in place |
ambiguous_width |
1 |
integer | cells an East-Asian ambiguous-width char takes: 1 (default, modern) | 2 (legacy CJK locales) |
[unicode]
| Key | Default | Type | Description |
|---|---|---|---|
normalization |
"none" |
string | form applied to SEARCH and COPY text: none (default) | nfc | nfd | nfkc | nfkd. Both sides must normalize the same way to match; never applied per-cell on ingest |
[keys]
Bind a key-spec to an action. The spec is one or more ‘+’-joined chords (“cmd+shift+k”); space-separate chords for a leader sequence (“ctrl+a ctrl+x”). Modifiers: cmd/super, ctrl, alt/option, shift. Keys: a printable char, fN, or a named key (enter tab escape space up down left right pageup pagedown home end backspace delete insert).
Actions: copy, paste, scroll_line_up/down, scroll_page_up/down, scroll_to_top/bottom, new_tab, new_window, close_tab, next_tab, prev_tab, increase_font_size, decrease_font_size, reset_font_size, toggle_fullscreen, clear_screen, clear_scrollback, clear, \r \t \e escapes), “macro:<name>” (run a [macros] entry), or
compose_key names a terminal-decoded compose (Multi_key) trigger: pressing it then a short run (Compose ’ e -> é, - - - -> em dash, < 3 -> heart, c = -> euro) inserts the composed character. Empty (default) disables it.
option_as_alt picks which Option keys act as Alt (Meta), sending ESC and the key for Emacs and shell word motions: none (default), left, right or both. An Option key it does not name types what the keyboard layout puts there, such as @ [ ] { } | ~ on German, Nordic or French layouts, and its dead-key accents. macOS only: Alt on Linux is always Meta, and the iPad app reads no config file, so its Option keeps the default. accessory_symbols keeps an ordered subset of the iOS keyboard symbols. An empty string hides the optional symbol keys.
| Key | Default | Type | Description |
|---|---|---|---|
compose_key |
"ctrl+space" |
string | |
option_as_alt |
"none" |
string | |
accessory_symbols |
"[]/~" |
string |
Examples:
[keys]"ctrl+alt+k" = "clear_scrollback""ctrl+a ctrl+x" = "send:\\x18""cmd+ctrl+d" = "macro:deploy"[macros]
Not set in the default file. The block below is the default file’s example.
Macros — named text snippets sent to the focused session. Each adds an item to the App > Macros menu; bind one to a key with the send: (\n \r \t \e \xNN \).
[macros]deploy = "git push\n"clear = "clear\n"[triggers]
Not set in the default file. The block below is the default file’s example.
Triggers — regex rules evaluated against each completed line, in file order. The regex is the key; the value is “<action>” or run_command (gated by allow_run_command), webhook (gated by allow_webhook; arg = http(s) URL, the match is POSTed as JSON). The run_command/webhook gates default OFF — terminal output is attacker-controllable, so a program that prints the right bytes runs whatever these allow. Off unless you turn them on per profile.
[triggers]allow_run_command = falseallow_webhook = false"[0-9]+ tests? passed" = "notify:Tests""BUILD FAILED" = "webhook:https://example.com/hook"[scripting]
Not set in the default file. The block below is the default file’s example.
Scripting hook — run an external program (Lua/Python/shell) at launch and parse its stdout into trigger/macro/charclass rules:
trigger <regex> = <action[:arg]>macro <name> = <body>charclass <name> = <regex>Gated OFF by default (enable runs an external program).
[scripting]enable = falseconfig_script = "/Users/me/.config/ubiquitty/rules.py"[experimental]
Not set in the default file. The block below is the default file’s example.
Sessions keep running in the background after you quit, and the windows, tabs and panes come back on the next launch. Shown commented because it is experimental: what a restored session contains is still moving, so the key is here to be discoverable rather than to be a default anyone builds on. The same toggle is Settings > “Restore Last Session on Launch”.
[experimental]session_persistence = false[debug]
Not set in the default file. The block below is the default file’s example.
[debug]show_build_hash = false # show the "<version> (<hash>)" build identity badge in # the titlebar (View > Show Build Hash, ⌃⌘⇧H); default off[[themes]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
Custom themes — one [[themes]] block per theme, appended after the built-ins. ANSI hex literals are #rrggbb or #rrggbbaa. Each [[themes]] entry adds an item to View > Theme.
Optional: the colour each status is drawn in (a failed job, a program waiting on you, a bell nobody has seen, a finished job, work in flight, and everything else). Left out, each comes from the theme’s own red, yellow, magenta, green and blue, and the midpoint of fg and bg.
[[themes]]name = "My Theme"is_dark = trueansi = [ "#1d1f21", "#cc6666", "#b5bd68", "#f0c674", "#81a2be", "#b294bb", "#8abeb7", "#c5c8c6", "#666666", "#d54e53", "#b9ca4a", "#e7c547", "#7aa6da", "#c397d8", "#70c0b1", "#eaeaea",]fg = "#ffffff"bg = "#282c34"cursor = "#ffffffaa"status_failed = "#cc6666"status_blocked = "#f0c674"status_attention = "#b294bb"status_done = "#b5bd68"status_working = "#81a2be"status_neutral = "#939598"status_progress = "#81a2be" # a progress bar; unset, macOS draws its accent[[profiles]]
An array of tables: repeat the block once per entry. The values below are an example, not defaults.
Profiles — named presentation bundles surfaced in the macOS File > New Window with Profile submenu. Each field is optional and layered over the live global config (the “Default” profile); an omitted field inherits the global value. theme is by name. scope is local | synced | ephemeral (reserved for the synced config store). startup_host, when set, opens the session against that host instead of the local shell: a [user@]host, optionally written as “ssh host” or “mosh host”. It names a host, not a command — options and other programs are refused, because a profile can be shared and a command here would run on the machine that opens it. parent names another profile to inherit unset fields from first (child -> parent -> … -> Default).
[[profiles]]name = "Production"parent = "Base"theme = "Ayu Mirage"font_family = "JetBrains Mono"font_size = 13line_spacing = 2padding_left = 8padding_right = 8padding_top = 4padding_bottom = 8startup_host = "ssh prod.example.com"[mac]
Not set in the default file. The block below is the default file’s example.
Platform overrides — a [mac] or [linux] block whose fields apply only on that platform, layered last over the resolved profile (so a [mac] font_family wins on a Mac, is ignored elsewhere). Same field names as a profile; an omitted field inherits. A [<plat>.keys] sub-table overrides keybindings per platform — a spec already bound globally is replaced, a new spec is added.
[mac]font_family = "SF Mono"[mac.keys]
Not set in the default file. The block below is the default file’s example.
[mac.keys]"cmd+k" = "clear_scrollback"[linux]
Not set in the default file. The block below is the default file’s example.
[linux]font_family = "DejaVu Sans Mono"Keys the parser accepts beyond the default file
The parser reads these keys as well. The default file does not list them, so they carry no default or description here; their values follow the type shown.
| Section | Key | Type |
|---|---|---|
[title] |
pane_app_title |
boolean |
[title] |
pane_dimensions |
boolean |
[title] |
pane_directory |
boolean |
[title] |
pane_directory_path |
boolean |
[title] |
pane_process |
boolean |
[title] |
pane_process_arguments |
boolean |
[title] |
pane_profile_name |
boolean |
[title] |
pane_program_status |
boolean |
[title] |
pane_shell_command |
boolean |
[title] |
pane_text |
string |
[title] |
pane_tty_name |
boolean |
Ubiquitty and this site are copyright © 2026 Stanislav Yaglo. Ubiquitty is licensed under the Apache License 2.0.
Apple, iPad, iPadOS, iPhone, Keychain, Mac, macOS, Metal, Swift and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries and regions.