gnome-screensaver-command
Control the GNOME screen saver
SYNOPSIS
gnome-screensaver-command [OPTION]…
PARAMETERS
-v, --version
Print release version and exit
-q, --query
Query screensaver state: prints disabled, active, blanked, or blanked,locked
-l, --lock
Lock the screen immediately
-p, --poke
Poke screensaver to unblank screen (simulate activity)
-i, --inhibit application-id
Inhibit screensaver; returns cookie (e.g., com.example.App)
-u, --uninhibit cookie
Remove inhibition using prior cookie
--replace
Replace existing screensaver inhibitor
-h, --help
Show help usage
DESCRIPTION
The gnome-screensaver-command provides a command-line interface to interact with the GNOME screensaver daemon, allowing users to query its state, lock the screen, deactivate it, or manage inhibitions programmatically. This is useful for scripts, keyboard shortcuts, or applications needing to control screen locking without graphical menus.
It supports querying whether the screensaver is active, blanked, or locked; immediately locking the screen; 'poking' to unblank it (e.g., simulating user activity); and inhibiting activation for specific applications using a cookie-based system. In modern GNOME environments (post-3.8), gnome-screensaver has been deprecated in favor of the built-in shell screensaver, but the command may still function or be aliased.
Common use cases include automating lock after idle time in custom workflows or integrating with media players to prevent interruption. Always check if the screensaver daemon is running, as commands fail otherwise.
CAVEATS
Fails if gnome-screensaver daemon not running (exit 2); deprecated in GNOME 40+ (use gnome-shell or logind instead); inhibitions require namespaced app IDs.
EXIT STATUS
0: success
1: general error
2: screensaver not running
QUERY OUTPUT EXAMPLES
disabled: inactive
active: running, screen on
blanked: screen blanked
blanked,locked: blanked and locked
HISTORY
Introduced with GNOME Screensaver ~2.28 (2009); default until GNOME 3.8 (2013); deprecated post-GNOME 3.26 as Mutter/gnome-shell integrated screensaver/locking.
