Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

First Run and Keybinds

Wayscriber has two run modes: daemon mode (recommended) and one-shot mode.

Wayscriber stays running in the background. You toggle the overlay on and off with a keyboard shortcut — instant, no startup delay. This is the best way to use wayscriber day-to-day.

Start the daemon:

systemctl --user enable --now wayscriber.service

Or run it directly:

wayscriber --daemon

Then add a keybind that runs wayscriber --daemon-toggle. For Hyprland Lua, add this to ~/.config/hypr/bindings.lua:

o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

For a traditional Hyprland config:

bind = SUPER, D, exec, wayscriber --daemon-toggle

On GNOME, add a Custom Shortcut in Settings → Keyboard with the command wayscriber --daemon-toggle.

Use only one toggle binding. Duplicate compositor bindings can fire twice and immediately undo the toggle. If your shortcut environment does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Press the shortcut to draw, press it again to hide.

Light passthrough shortcuts

Light passthrough mode makes the overlay click-through until drawing is explicitly enabled. The default F6 keybinding is a Wayscriber in-overlay shortcut: it works while the overlay has focus, but once passthrough is active Wayscriber may no longer receive that keypress.

Once passthrough is active, normal keyboard and pointer input goes to the app underneath. For reliable control, add compositor/global shortcuts that run:

wayscriber --light-toggle
wayscriber --light-draw-toggle
wayscriber --light-draw-on
wayscriber --light-draw-off

Use --light-toggle for passthrough on/off, including getting back out after input is passed through. Use --light-draw-toggle for sticky drawing, and --light-draw-on / --light-draw-off for draw-while-held. See Compositor Guides for Hyprland and KDE examples. Light passthrough requires layer-shell support; it is disabled on the xdg-shell fallback.

One-shot mode

Opens the overlay once and exits when you close it. Good for quick tests or occasional use — no service needed.

wayscriber --active

Default keys you should know

  • F1 opens help (F10 is the alternative)
  • Shift+F1 opens the quick reference
  • F9 shows or hides the toolbars
  • F2 cycles the top strip through full, micro chip, and hidden
  • F11 opens the configurator (if installed)
  • About Wayscriber (version, links, update status) has no default key. Reach it from the top strip’s chrome, the overflow’s Settings… popover, the help overlay footer, or the command palette — or bind open_about yourself.
  • F4 toggles the status bar (F12 is the alternative)
  • Ctrl+Shift+F freezes/unfreezes the screen
  • Ctrl+Shift+M toggles presenter mode
  • F6 enters light passthrough while the overlay has focus; use a global wayscriber --light-toggle shortcut to get back out
  • Ctrl+Shift+H toggles click highlights
  • Ctrl+Shift+K toggles the input HUD (keystrokes and clicks on screen)
  • Ctrl+K opens the command palette. It shows action icons, category headers, and persisted recent commands. Use arrows/Home/End to navigate, Ctrl+U to clear, and Ctrl+Backspace to delete the previous word. Search Save preset to save slots 1–5 from the palette.
  • Ctrl+Shift+B opens the board picker
  • Ctrl+Alt+Shift+Left/Right moves overlay focus to previous/next output
  • V toggles the selection tool
  • Hold Alt and drag to select/move shapes
  • Ctrl+D duplicates selected shapes
  • Delete removes selected shapes
  • Escape or Ctrl+Q exits the overlay

Guided tour and quick help

  • First launch shows a short guided tour. Space/Enter advances, Backspace goes back, Escape skips.
  • The tour resolves shortcut text from your current bindings and covers drawing, colors/thickness, the middle-click radial flick gesture, and opening Boards & Pages from the status bar or current board-picker shortcut.
  • Replay it from the searchable Help footer or from the command palette: Ctrl+K, then search for “Replay Tour”.
  • For output actions, open the command palette and search for “monitor” or “display”.
  • The full help overlay supports fuzzy search; just start typing to filter shortcuts. Rows are clickable, and the layout uses one or two columns depending on available width.
  • After the tour, the shortcut coach may show a limited number of hint notifications when a toolbar, palette, Canvas-popover, or zoom-chip action has a useful keyboard shortcut. It is rate-limited and suppressed while other onboarding UI is active.
  • Later sessions can show staggered, capped hints for the status-bar board picker, Canvas… popover, and bottom-right zoom chip. They only appear when the named surface is reachable and never stack on top of other feedback.
  • If you deliberately use deprecated side_layout = "panel", a once-per-session notice points to the style pill, Canvas popover, zoom chip, status bar, presets island, and Session/Settings overflow entries.