Keybindings

The complete built-in keymap, and how to change it. Bindings are grouped by context: the terminal deliberately steals nothing, so every bare key reaches your shell. The third column is the action id you use in [keymap].

Keys are listed for both platforms wherever they differ. The ctrl-w chords, and every bare key in the file tree, the workspaces panel, the overlays, and copy mode, are identical on macOS and Linux. Where macOS uses cmd, Linux uses ctrl-shift — the usual terminal convention, so plain ctrl-c stays the shell's — and alt-1 … alt-9 for tabs, because Super belongs to the window manager: nothing is bound to it. A row tagged mac only has no Linux binding at all; that job is the window manager's.

How contexts work

Everything terminal-scoped is either modifier-prefixed (cmd-… on macOS, ctrl-shift-… on Linux) or sequence-led (ctrl-w then a key), and bound at the root, so no bare keystroke is taken away from the shell. The file tree, the workspaces panel, and the theme picker are modeless lists with no text input, so bare letters are free there. The command palette has a text input, so only arrows and ctrl-n / ctrl-p move its selection. Copy mode is the one place in the terminal where bare keys are legal: nothing typed there reaches the shell, so it has its own context, terminal_vi.

Configuring

Add a [keymap] table to config.toml: keystroke on the left, action id on the right. Anything you don't mention keeps its default. Changes apply live when you save.

[keymap]
# on Linux, write ctrl-shift-… where a Mac uses cmd-…
"cmd-shift-p"  = "app::palette"
"ctrl-w e"     = "pane::equalize"
"cmd-shift-]"  = "tab::next"

# Unbind by assigning nothing.
"cmd-d"        = ""

[keymap.file_tree]    # context-scoped tables
"y"            = "tree::refresh"

[keymap.terminal]
"cmd-shift-c"  = "terminal::copy"

• Keystrokes are modifier-…-key, with cmd, ctrl, alt, shift, and fn as modifiers, in any order. Separate the steps of a chord with a space: "ctrl-w z". Named keys: up, down, left, right, enter, escape, tab, space, backspace, f1… On Linux, cmd means Super: it parses and binds, but under Hyprland, GNOME, or KDE the compositor usually takes Super combos before OmniPTY sees them, which is why none of the defaults use it. Prefer ctrl-shift or alt.
• Contexts. Pairs directly under [keymap] bind at the root and work everywhere. Subtables scope a binding: [keymap.terminal], [keymap.terminal_vi] (copy mode, where bare keys are allowed), [keymap.file_tree], [keymap.workspaces], and [keymap.overlay] (the theme picker and command palette). A binding in a deeper context wins over the same key at the root.
• The shell comes first. A bare key — no cmd, ctrl, or alt — at the root or in [keymap.terminal] would hide that key from whatever you're running, so OmniPTY refuses it and tells you why. Use a modifier, or a ctrl-w chord.
• Mistakes are reported, not ignored. An unknown action id (with a "did you mean" suggestion), a keystroke that doesn't parse, or a bare key in the terminal each produce a line in the error toast in the bottom-right corner. Everything else in the table still binds.
• Starting from scratch. replace_defaults = true under [keymap] drops the built-in map entirely. Every action OmniPTY ships after that is unreachable until you bind it, so prefer overriding.

Application

Terminal

Tabs & windows

Splits & focus

The drawer

In the file tree

In the workspaces panel

In the palette, history, file finder, and theme picker

In copy mode

ctrl-w [ turns the scrollback into a vim buffer. These keys are fixed — they're vim's — but anything else can be bound in [keymap.terminal_vi], bare keys included, since nothing typed here reaches the shell.

Commands without a default binding

These have no default key. They live in the menus at the path shown — the macOS menu bar, or the ☰ button in the top-left corner of a Linux window. Every one is also in the command palette (cmd-shift-p / ctrl-shift-p) and can be bound in [keymap]: