Keybindings

Built-in bindings live under [keybinds] in wm.toml. Each action accepts one chord, an array of chords, or an empty array that removes every chord for that action:

[keybinds]
cycle_focus = ["Super+Tab", "Alt+Tab"]
close_focused = "Super+Q"
reload_rules = []

Omitting an action keeps its compiled default. The packaged wm.toml adds convenient bindings for layout slots and column movement that are not all compiled defaults.

Change a shortcut safely

Open Settings → Aqueous → Shortcuts, find the action and choose its recording control. Wait until recording is ready, then press the chord. Escape cancels; modifier-only presses are ignored. Recording inhibits normal compositor shortcuts. If inhibition is unavailable, cancel and type the chord instead.

Validate, Apply & save, then test the shortcut. Restore its previous chord to undo. In TOML, [] disables an action; deleting its assignment restores the compiled default. Check for duplicate chords: the last declaration wins. The recorder changes one binding; it does not import another compositor’s config.

For Alt+Tab cycling alongside Super+Tab, edit the existing [keybinds] table:

[keybinds]
cycle_focus = ["Super+Tab", "Alt+Tab"]

Save to reload. This cycles through the active workspace’s focus history.

Choose a window or workspace

Super+Tab cycles focus. Super+W opens the active workspace’s overview.
Super+1 through Super+9 switch workspaces on the target output. Super+Shift+1 through 9 move a window there; select the workspace to follow it.
Output bindings switch displays or move windows. Workspace numbers are per output; IPC IDs are session-local identifiers.

For a visual switcher across outputs and workspaces, bind these unassigned actions instead of using Alt+Tab for cycle_focus:

[keybinds]
window_switcher_next = "Alt+Tab"
window_switcher_previous = "Alt+Shift+Tab"

This switcher keeps a stable order when focus changes, rather than MRU order. It visits non-minimized, activatable windows and switches to the selected window’s display and workspace. Keep cycle_focus on a different chord. Save and try both directions; restore the old bindings or use [] to unbind.

Pearl’s Cycle windows widget also provides the switcher, with a fallback for older compositors. Use Launcher to find minimized windows too.

Minimize, maximize and restore a window

These are the compiled shortcuts; custom bindings can change them.

Task	Shortcut	Return
Minimize	`Super+N`	`Super+Shift+N` restores the last minimized window.
Maximize	`Super+Shift+M`	Press again to restore.
Fullscreen	`Super+Shift+F`	Press again to leave fullscreen.
Float a tiled window	`Super+Shift+Space`	Press again to return it to the layout.

Minimized windows leave the layout and focus cycle; Launcher can activate them. Fullscreen uses the full output; maximize normally uses its usable area. Shell menus, CLI requests and client buttons may reject minimize/maximize on a tiled window even when native shortcuts work. Shell records expose can_minimize, can_maximize and can_activate. Title-bar buttons also depend on the app’s decorations and layout policy.

Chord grammar

Join case-insensitive tokens with +.

Primary modifier: Super, Mod4, Logo, or Win.
Physical Super modifier: Meta, even when AQUEOUS_MOD=Alt.
Other modifiers: Ctrl/Control, Alt/Mod1, and Shift.
Keys: printable ASCII, F1–F24, navigation/editing names, punctuation names, Print, CapsLock, and common XF86 media/display/brightness keys.
Scroll directions: WheelUp, WheelDown, WheelLeft, and WheelRight, including accumulated touchpad scroll steps.

AQUEOUS_MOD=Alt makes Alt the primary modifier; in that mode literal Alt is still resolved consistently. Use Meta to address the physical Super key.

Session, focus, and overview

Action	Compiled default
`toggle_start_menu`	`Super+Space`
`spawn_terminal`	`Super+Return`
`screenshot`	`Print`
`close_focused`	`Super+Q`
`toggle_overview`	`Super+W`
`cycle_focus`	`Super+Tab`
`focus_left/right/up/down`	`Super+H/L/K/J`
`reload_config`	`Super+R`
`lock_screen`	`Super+Ctrl+L`
`untrap_pointer`	`Super+grave`

The overview contains every focusable window on the active workspace, including off-viewport scrolling members. Navigate with arrows, H/J/K/L, Tab, or pointer input, then confirm a window or close the overview.

Four command actions run values from [actions]:

[actions]
toggle_start_menu = "aqueous-shell-action launcher"
spawn_terminal = "ghostty"
screenshot = "aqueous-shell-action screenshot"
lock_screen = "aqueous-shell-action lock"

These commands use the packaged stable session helpers, which dispatch to the selected shell. Co-installable Git instances use their matching suffixed helpers. A core-only installation needs its own launcher, terminal, screenshot tool and locker commands. Binding an action alone does not install or configure them.

Layout-aware movement

[keybinds]
move_window_left = "Super+Shift+Left"
move_window_right = "Super+Shift+Right"
move_window_up = "Super+Shift+Up"
move_window_down = "Super+Shift+Down"

Movement follows the active engine:

Tile, grid, dwindle, and reverse-dwindle swap geometric neighbors.
Scrolling joins adjacent columns or reorders members vertically.
Monocle changes z-stack order.
Game Mode delegates to its active remainder while the anchor stays fixed.
Composable delegates to the member’s child; cross-region pointer drops exchange membership.
Stacking uses the configured fine movement step.

Scrolling actions

Action	Typical/default chord
`scroll_viewport_left/right`	`Super+Comma/Period` (legacy names)
`scroll_viewport_left_arrow/right_arrow`	`Super+Left/Right`
`wheel_scroll_left/right`	`Super+WheelUp/Down`
`scroll_viewport_up/down`	`Super+Up/Down`
`wheel_scroll_up/down`	`Alt+Meta+WheelUp/Down`
`consume_window_into_column`	`Super+Ctrl+J`
`expel_window_from_column`	`Super+Ctrl+K`
`toggle_scrolling_full_width`	`Super+Shift+Z`
`move_column_left/right`	packaged as `Super+Shift+H/L`

The primary-modifier wheel chord pans columns; primary+Alt moves within a vertical column. See Layouts for pointer insertion and resize behavior.

Wheel actions accept the same string, array, or empty-array syntax as keyboard actions. Rebinding one removes its previous default without changing the arrow shortcuts:

[keybinds]
wheel_scroll_left = ["Ctrl+WheelUp", "Ctrl+WheelLeft"]
wheel_scroll_right = ["Ctrl+WheelDown", "Ctrl+WheelRight"]
wheel_scroll_up = []
wheel_scroll_down = []

[keybinds.custom]
"Super+WheelUp" = "builtin:focus_workspace_up"
"Super+WheelDown" = "builtin:focus_workspace_down"

Custom wheel chords can run any supported action or command outside scrolling layouts, too. An explicit custom chord replaces the default on that chord. Matched steps are consumed even when the action has no effect; unmatched directions reach the application. Wheel input cannot hold untrap_pointer. Locks, shortcut inhibition, overview, interactive drags, and XWayland keyboard grabs prevent wheel bindings from running.

Layout selection and composable regions

The four set_layout_primary/secondary/tertiary/quaternary actions resolve through [layout.slots]. Direct custom actions can select an ID or slot:

[keybinds.custom]
"Super+Alt+D" = "set_layout:dwindle"
"Super+Alt+Shift+D" = "set_layout:reverse-dwindle"
"Super+Alt+F" = "set_layout:stacking"
"Super+Alt+C" = "set_layout:composable"
"Super+Alt+1" = "builtin:focus_composable:a"
"Super+Alt+Shift+1" = "builtin:move_to_composable:a"

Workspaces and outputs

Aqueous creates nine pinned workspaces per output. One is active on each output, and each window belongs to at most one workspace.

[keybinds]
focus_workspace_1 = "Super+1" # through focus_workspace_9
move_to_workspace_1 = "Super+Shift+1" # through move_to_workspace_9
focus_workspace_up = "Super+Bracketleft"
focus_workspace_down = "Super+Bracketright"
focus_previous_workspace = "Super+BackSpace"
move_to_workspace_up = "Super+Shift+Bracketleft"
move_to_workspace_down = "Super+Shift+Bracketright"

focus_output_left = "Super+Ctrl+Comma"
focus_output_right = "Super+Ctrl+Period"
move_to_output_left = "Super+Shift+Comma"
move_to_output_right = "Super+Shift+Period"
rotate_output_clockwise = "Super+Ctrl+R"

Output navigation uses physical rectangles rather than connector iteration order. Rotation targets only the enabled output beneath the pointer and is not persisted to TOML.

An explicitly selected output remains the target for subsequent workspace and window actions even when it is empty. Output navigation moves the pointer to the destination; mouse-follows-focus can additionally place it inside the newly focused window.

Window states

[keybinds]
toggle_fullscreen = "Super+Shift+F"
toggle_maximize = "Super+Shift+M"
toggle_floating = "Super+Shift+Space"
toggle_minimize = "Super+N"
unminimize_last = "Super+Shift+N"

Toggles remember prior presentation. Aqueous keeps one fullscreen owner per output; minimized windows leave layout and focus selection until restored. toggle_maximize_horizontal and toggle_maximize_vertical are available as unbound partial-maximize actions.

Stacking and freeform actions

These built-ins are intentionally unbound so existing configurations keep their chords:

Group	Actions
Stack order	`raise_window`, `lower_window`, `toggle_always_above`, `toggle_always_below`
Fine movement	`nudge_floating_left/right/up/down`
Coarse movement	`nudge_floating_coarse_left/right/up/down`
Grow an edge	`resize_floating_left/right/up/down`
Shrink an edge	`shrink_floating_left/right/up/down`
Standard snap	`snap_left/right/up/down`, `snap_center`, four corner actions, `unsnap`
Named stacking snap	`builtin:snap_zone:<layout>/<zone>`, `builtin:set_snap_layout:<layout>`, `builtin:cycle_snap_layout[_reverse]`
Legacy custom snap	`builtin:snap_zone:a` through `d`, `cycle_snap_zone`
Fit/partial maximize	`fit_floating_to_output`, `toggle_maximize_horizontal/vertical`
Edge operations	`move_floating_to_edge_<direction>`, `grow_floating_to_edge_<direction>`

The pixel increments, gap, resistance, and top-edge behavior come from [layout.options.stacking].

Custom chords

[keybinds.custom] maps a chord to one verb:

[keybinds.custom]
"Super+E" = "spawn:nemo"
"Super+Shift+V" = "launch:vesktop-ssd"
"Super+Shift+S" = "builtin:screenshot"
"Alt+F4" = "builtin:close_focused"
"Super+Alt+2" = "builtin:snap_zone:work/terminal"
"Super+Alt+W" = "builtin:set_snap_layout:work"
"Super+Alt+Space" = "builtin:cycle_snap_layout"
"XF86AudioRaiseVolume" = "spawn:wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+"

spawn:<command> runs a detached /bin/sh -c command.
launch:<profile> directly executes a named [[application]] profile with its typed argument and environment arrays, without a shell.
set_layout:<id-or-slot> selects a layout directly.
builtin:<action> invokes any canonical built-in action, including argument forms for snap zones and composable regions.

Use launch: for application-specific Wayland or decoration switches where argument boundaries matter. Profiles are defined in wm.toml; see Application launch profiles.

builtin:cycle_snap_layout_reverse cycles named layouts in the opposite direction. Named layout and zone actions are consumed only on a full stacking workspace; they remain inert in every other layout, including for persistent floating overlays.

If several declarations resolve to the same chord, the last declaration wins. A bound Caps Lock chord is consumed by Aqueous and does not toggle the lock; without a binding, Caps Lock retains normal XKB behavior.