CLI

Overview

The CLI is primarily for Linux users, especially those using tiling window managers or Wayland compositors where global keyboard shortcuts don’t always work natively. On macOS and Windows, the GUI handles everything and you generally don’t need the command line.

Handy can be launched from the command line with flags to customize its behavior. This is useful for scripting, automation, and window manager integration.

Flags

handy [OPTIONS]
FlagDescription
--model <MODEL>Set the speech-to-text model to use
--language <LANG>Set the language code (e.g., en, es, de)
--push-to-talkEnable push-to-talk mode
--no-overlayDisable the recording overlay
--debugEnable debug logging
--toggle-transcriptionToggle transcription on/off in a running instance
--toggle-transcription-post-processToggle transcription with post-processing on/off

The --toggle-transcription and --toggle-transcription-post-process flags communicate with an already-running Handy instance. If Handy is recording, it stops and transcribes. If idle, it starts recording. This is useful for binding to window manager shortcuts.

Signal Control

On macOS and Linux, you can control a running Handy instance using Unix signals:

SignalAction
SIGUSR2Toggle transcription (start/stop recording)
SIGUSR1Toggle transcription with post-processing
# Toggle transcription
pkill -USR2 -x handy

# Toggle transcription with post-processing
pkill -USR1 -x handy

Signal control is the recommended approach for Wayland where global keyboard shortcuts often don’t work natively. Bind the signal command to a shortcut in your compositor.

Scripting

You can use Handy in scripts to capture speech-to-text output. This is especially useful for automation workflows.

Window Manager Integration

Handy works well with tiling window managers and custom keybinding setups. Use either CLI flags or signals to control Handy from your compositor.

Hyprland

# Using signals (recommended)
bind = $mainMod SHIFT, period, exec, pkill -USR2 -x handy

# Using CLI flags
bind = $mainMod SHIFT, period, exec, handy --toggle-transcription

sway / i3

# Using signals (recommended)
bindsym $mod+Shift+period exec pkill -USR2 -x handy

# Using CLI flags
bindsym $mod+Shift+period exec handy --toggle-transcription

GNOME (Wayland)

GNOME on Wayland doesn’t support global shortcuts from third-party apps. Use a custom shortcut that sends a signal:

  1. Open Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts
  2. Add a new shortcut with the command: pkill -USR2 -x handy
  3. Assign your preferred key combination