OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config low common DISPUTE

Run hyprctl from a TTY, cron or SSH by setting the instance signature

hyprlandomarchyarchendeavouroscachyosmanjarosystemd-bootgrub
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

The diagnosis and most commands are right: hyprctl talks to $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/ (confirmed on the IPC wiki), hyprctl instances is a documented info command, --instance is a real flag (hyprctl.usage: -i | --instance), --batch is documented, and the batching-for-performance advice comes straight from the wiki's own warning that 'any spam of the utility will cause slowdowns. It's recommended to use --batch'. The log path is correct. The defect is the signature-export recipe, which is offered specifically 'for scripts and units', the one context where it is most likely to fail. In a system unit or a cron job XDG_RUNTIME_DIR is not set, so the path collapses to /hypr and the command silently produces nothing. And ls -t | head -n 1 picks the newest entry by mtime, which can be a stale directory left by a crashed session or a non-instance entry, so it can also silently target the wrong thing.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.

Symptom

Running hyprctl from a TTY, a cron job, a systemd unit or an SSH session fails: no output, or it targets the wrong Hyprland when you have more than one running.

Cause

hyprctl talks to a per-instance UNIX socket under $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/. Outside the compositor's own environment that variable is unset, so hyprctl has nothing to connect to. With multiple instances it needs to be told which.

Fix

Diagnosis, --instance, --batch and the log path are all correct. Replace the export recipe, which fails in exactly the script/unit context it is recommended for.

Set XDG_RUNTIME_DIR explicitly first, because it is unset in system units and cron:


export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"

Then prefer targeting by index, which needs no signature guessing:


hyprctl instances                 # lists running instances
hyprctl --instance 0 monitors     # put flags BEFORE the subcommand
hyprctl --instance 0 dispatch 'hl.dsp.submap("reset")'

If you must derive the signature, pick a live socket rather than the newest directory, so stale dirs from crashed sessions cannot win:


for d in "$XDG_RUNTIME_DIR"/hypr/*/; do
  [ -S "$d/.socket.sock" ] || continue
  export HYPRLAND_INSTANCE_SIGNATURE=$(basename "$d")
  break
done
hyprctl monitors

For a systemd *user* unit, the cleanest fix is After=graphical-session.target plus PartOf=graphical-session.target and letting Hyprland's dbus-update-activation-environment seed the environment (see the portal record).

Verify

hyprctl monitors returns your outputs from the TTY/script context.

Sources

hyprctl-fails-outside-session-instance-signature