Command-Line Interface
Jay provides a comprehensive CLI for controlling the compositor, managing displays, input devices, clients, and more. All subcommands communicate with the running compositor over the Wayland protocol unless otherwise noted.
Tip
Generate shell completions for tab-completion support:
~$ jay generate-completion bash > ~/.local/share/bash-completion/completions/jay ~$ jay generate-completion zsh > ~/.zfunc/_jay ~$ jay generate-completion fish > ~/.config/fish/completions/jay.fish ~$ jay generate-completion elvish # pipe to appropriate location ~$ jay generate-completion powershell # pipe to appropriate location
Every subcommand accepts a global --log-level option (trace, debug,
info, warn, error, off) that controls the verbosity of the CLI tool itself.
JSON Output
Most query and status commands can output machine-readable JSON instead of
human-readable text. Pass the global --json flag before the subcommand:
~$ jay --json randr
~$ jay --json clients
~$ jay --json idle
Each command prints one or more JSON objects, one per line (JSONL format). This
makes it easy to process with tools like jq:
~$ jay --json randr | jq '.drm_devices[].connectors[].name'
~$ jay --json clients | jq 'select(.pid != null) | .pid'
By default, fields that are empty arrays, null, or false are omitted from
the output to reduce noise. To include every field, pass --all-json-fields:
~$ jay --all-json-fields --json randr
Supported Commands
The following commands support --json:
jay clients- One JSON object per client.
jay color-management status- Color management enabled/available status.
jay config path- The config file path as a JSON string.
jay idle status- Idle interval, grace period, and inhibitors.
jay input show,jay input seat <seat> show,jay input device <id> show- Seats and input devices with all properties.
jay log --path- The log file path as a JSON string.
jay pid- The compositor PID as a JSON number.
jay randr show- DRM devices, connectors, outputs, modes, and display properties.
jay seat-test- Streaming JSONL – one JSON object per input event (key, pointer, touch, gesture, tablet, switch).
jay tree query- One JSON object per root node, with children nested recursively.
jay version- The version string as a JSON value.
jay xwayland status- Xwayland scaling mode and implied scale.
Tip
Mutating commands (e.g.,
jay idle set,jay randr output ... enable) produce no output, so--jsonhas no effect on them.
Running
jay run
Start the compositor.
~$ jay run
Optionally specify which backends to try (comma-separated, tried in order):
~$ jay run --backends x11,metal,headless
The default order is x11,metal. The first backend that can be started is
used. metal is the native DRM/KMS backend for bare-metal sessions.
jay quit
Stop the running compositor.
~$ jay quit
jay pid
Print the PID of the running compositor.
~$ jay pid
jay version
Print the Jay version.
~$ jay version
Configuration
jay config init
Generate a configuration file pre-populated with all defaults.
~$ jay config init
If a config already exists, pass --overwrite to replace it (the old file is
backed up):
~$ jay config init --overwrite
Important
Once a config file exists, the entire built-in default configuration is replaced – not merged. An empty config file means no shortcuts, no startup actions, nothing. Always use
jay config initto start with a working configuration.
jay config path
Print the path to the config file.
~$ jay config path
jay config open-dir
Open the configuration directory with xdg-open.
~$ jay config open-dir
Display & Graphics
All display and GPU commands live under jay randr.
Showing Current Settings
~$ jay randr
~$ jay randr show
~$ jay randr show --modes # include all available modes
~$ jay randr show --formats # include all available framebuffer formats
GPU / Card Commands
Set the primary (render) GPU:
~$ jay randr card card0 primary
Set the graphics API:
~$ jay randr card card0 api vulkan
~$ jay randr card card0 api opengl
Toggle direct scanout:
~$ jay randr card card0 direct-scanout enable
~$ jay randr card card0 direct-scanout disable
Adjust the page-flip margin (in milliseconds, default 1.5):
~$ jay randr card card0 timing set-flip-margin 1.5
Output Commands
Enable or disable an output:
~$ jay randr output DP-1 enable
~$ jay randr output DP-1 disable
Set the position:
~$ jay randr output DP-1 position 1920 0
Set the scale (fractional scaling supported):
~$ jay randr output DP-1 scale 1.5
~$ jay randr output DP-1 scale --round-to-float 1.333
Set the mode (width, height, refresh rate in Hz):
~$ jay randr output DP-1 mode 2560 1440 144.0
Set the transform:
~$ jay randr output DP-1 transform rotate-90
~$ jay randr output DP-1 transform none
Available transforms: none, rotate-90, rotate-180, rotate-270, flip,
flip-rotate-90, flip-rotate-180, flip-rotate-270.
Override the non-desktop setting:
~$ jay randr output DP-1 non-desktop true
~$ jay randr output DP-1 non-desktop default
Configure VRR (variable refresh rate):
~$ jay randr output DP-1 vrr set-mode always
~$ jay randr output DP-1 vrr set-mode variant3
~$ jay randr output DP-1 vrr set-cursor-hz 240
~$ jay randr output DP-1 vrr set-cursor-hz none
VRR modes: never, always, variant1 (one or more fullscreen apps),
variant2 (single fullscreen app), variant3 (single fullscreen app with
game/video content type). Pass none to set-cursor-hz to remove the cursor
Hz cap.
Configure tearing:
~$ jay randr output DP-1 tearing set-mode variant3
Tearing modes: never, always, variant1 (one or more applications
displayed fullscreen), variant2 (single application displayed fullscreen),
variant3 (default – single displayed application that requested tearing).
Set the framebuffer format:
~$ jay randr output DP-1 format set xrgb8888
Set the output color space and EOTF (for HDR):
~$ jay randr output DP-1 colors set bt2020 pq
~$ jay randr output DP-1 colors set default default
Set the brightness (in cd/m^2, or default):
~$ jay randr output DP-1 brightness 203
~$ jay randr output DP-1 brightness default
Set the blend space:
~$ jay randr output DP-1 blend-space linear
~$ jay randr output DP-1 blend-space srgb
Enable or disable native gamut usage:
~$ jay randr output DP-1 use-native-gamut true
~$ jay randr output DP-1 use-native-gamut false
Virtual Outputs
~$ jay randr virtual-output create my-virtual-display
~$ jay randr virtual-output remove my-virtual-display
Input
All input commands live under jay input.
Showing Input Devices
~$ jay input
~$ jay input show
~$ jay input show -v # verbose output with device details
Seat Commands
Show seat information:
~$ jay input seat default show
~$ jay input seat default show -v
Set keyboard repeat rate (repeats per second, initial delay in ms):
~$ jay input seat default set-repeat-rate 25 600
Set the keymap from RMLVO names:
~$ jay input seat default set-keymap-from-names -l de
~$ jay input seat default set-keymap-from-names -l us -v intl -o compose:ralt
Set the keymap from a file (or stdin):
~$ jay input seat default set-keymap /path/to/keymap.xkb
Retrieve the current keymap:
~$ jay input seat default keymap > current.xkb
Toggle hardware cursor:
~$ jay input seat default use-hardware-cursor true
~$ jay input seat default use-hardware-cursor false
Set cursor size:
~$ jay input seat default set-cursor-size 24
Configure the simple (XCompose-based) input method:
~$ jay input seat default simple-im enable
~$ jay input seat default simple-im disable
~$ jay input seat default simple-im reload
Device Commands
Show device information:
~$ jay input device 42 show
Set acceleration profile and speed:
~$ jay input device 42 set-accel-profile flat
~$ jay input device 42 set-accel-profile adaptive
~$ jay input device 42 set-accel-speed -0.5
Configure tap behavior:
~$ jay input device 42 set-tap-enabled true
~$ jay input device 42 set-tap-drag-enabled true
~$ jay input device 42 set-tap-drag-lock-enabled false
Set left-handed mode:
~$ jay input device 42 set-left-handed true
Set natural scrolling:
~$ jay input device 42 set-natural-scrolling true
Set pixels per scroll-wheel step:
~$ jay input device 42 set-px-per-wheel-scroll 30.0
Set the transform matrix (2x2):
~$ jay input device 42 set-transform-matrix 1.0 0.0 0.0 1.0
Set the calibration matrix (2x3, for touchscreens):
~$ jay input device 42 set-calibration-matrix 1.0 0.0 0.0 0.0 1.0 0.0
Set the click method:
~$ jay input device 42 set-click-method clickfinger
~$ jay input device 42 set-click-method button-areas
~$ jay input device 42 set-click-method none
Toggle middle button emulation:
~$ jay input device 42 set-middle-button-emulation true
Set a per-device keymap:
~$ jay input device 42 set-keymap /path/to/keymap.xkb
~$ jay input device 42 set-keymap-from-names -l de
~$ jay input device 42 keymap > device.xkb
Attach / detach a device from a seat:
~$ jay input device 42 attach default
~$ jay input device 42 detach
Map a device to a specific output:
~$ jay input device 42 map-to-output DP-1
~$ jay input device 42 remove-mapping
Idle & Locking
jay idle
Show idle status, including the current interval, grace period, and active inhibitors:
~$ jay idle
~$ jay idle status
jay idle set
Set the idle interval. Durations can be specified in flexible formats:
~$ jay idle set 10m
~$ jay idle set 1m 30s
~$ jay idle set disabled
jay idle set-grace-period
Set the grace period (screens go black but are not locked/disabled):
~$ jay idle set-grace-period 30s
~$ jay idle set-grace-period disabled
jay unlock
Unlock the compositor. This is useful when the screen locker crashes and the
session remains locked. Run it from another TTY or via SSH. You must set
WAYLAND_DISPLAY to the socket of the Jay compositor:
~$ WAYLAND_DISPLAY=wayland-1 jay unlock
Logging
jay log
Open the log file in less:
~$ jay log
~$ jay log -f # follow mode (like tail -f)
~$ jay log -e # jump to end of log
~$ jay log --path # print the log file path instead
jay set-log-level
Change the log level at runtime:
~$ jay set-log-level debug
~$ jay set-log-level info
Available levels: trace, debug, info, warn, error, off.
Screenshots
jay screenshot
Take a screenshot of the entire display:
~$ jay screenshot
~$ jay screenshot --format png
~$ jay screenshot --format qoi
~$ jay screenshot my-screenshot.png
If no filename is given, the screenshot is saved as
%Y-%m-%d-%H%M%S_jay.<ext> in the current directory. The filename supports
strftime format specifiers.
Clients & Windows
jay clients
List all connected clients:
~$ jay clients
~$ jay clients show all
Show a specific client by ID:
~$ jay clients show id 42
Interactively select a window and show its client:
~$ jay clients show select-window
Kill a client by ID:
~$ jay clients kill id 42
Interactively select a window and kill its client:
~$ jay clients kill select-window
jay tree query
Inspect the compositor’s surface tree:
~$ jay tree query root
~$ jay tree query -r root # recursive
~$ jay tree query -r --all-clients root # show client details for every node
~$ jay tree query workspace-name main
~$ jay tree query select-workspace
~$ jay tree query select-window
Xwayland
jay xwayland
Show Xwayland status (scaling mode, implied scale):
~$ jay xwayland
~$ jay xwayland status
jay xwayland set-scaling-mode
~$ jay xwayland set-scaling-mode default
~$ jay xwayland set-scaling-mode downscaled
In downscaled mode, X11 windows are rendered at the highest integer scale and
then downscaled, which can improve sharpness on HiDPI displays.
Color Management
jay color-management
Show color management status:
~$ jay color-management
~$ jay color-management status
jay color-management enable / disable
~$ jay color-management enable
~$ jay color-management disable
Other Commands
jay control-center
Open the Control Center GUI:
~$ jay control-center
jay portal
Run the Jay desktop portal (provides screen sharing and other XDG desktop portal interfaces):
~$ jay portal
Normally the portal is started automatically. This command is for running it manually or debugging.
jay seat-test
Test input events from a seat. Prints all keyboard, pointer, touch, gesture, tablet, and switch events to stdout:
~$ jay seat-test
~$ jay seat-test default
~$ jay seat-test -a # test all seats simultaneously
jay run-privileged
Run a program with access to a privileged Wayland socket:
~$ jay run-privileged my-program --arg1
jay run-tagged
Run a program with a tagged Wayland connection. All Wayland connections from the spawned process tree will carry the specified tag, which can be matched in client rules:
~$ jay run-tagged my-tag firefox
jay generate-completion
Generate shell completion scripts:
~$ jay generate-completion bash
~$ jay generate-completion zsh
~$ jay generate-completion fish
~$ jay generate-completion elvish
~$ jay generate-completion powershell