hyprctl keyword silently does nothing under a Lua config, so use eval or repl
The core advice is right and the replacement commands are correct: eval/dispatch take Lua expressions, single-quoting the outer string is the right shell hygiene, hyprctl repl is a real interactive Lua REPL (Ctrl+D to exit) and the wiki's own examples are hyprctl repl 'hl.get_active_window().class' and the get_windows loop, hyprctl getoption uses section.option dotted form, nothing set with eval survives a reload, and the quoted 0.55 error string is exact: src/debug/HyprCtl.cpp at tag v0.55.0 contains return "keyword can't work with non-legacy parsers. Use eval.";. But the stated mechanism is wrong and so is one command. Reading hyprctl/src/main.cpp: the reply is printed by log() -> std::println i.e. STDOUT, and request() returns non-zero (7) only when the reply starts with error:. Neither the 0.55 keyword message nor 0.56's reply starts with error:, so the exit code is 0 and the text lands on stdout, which means a $(...) capture actually DOES receive the message, while callers that check $? are the ones fooled. The record has the failure inverted. Also, on current main keyword is no longer a registered socket1 command at all (src/ipc/s1/Commands.cpp registers dispatch/eval/repl/getoption/... but no keyword), so src/ipc/s1/S1.cpp answers unknown request. Finally hyprctl descriptions | jq -r '.[].value' is wrong: Config::Values::getAsJson emits objects with name, description, default, current. There is no value key (and no type/range keys), so that pipeline prints a column of nulls.
hyprctl eval 'hl.monitor({ output = "...", disabled = true })' takes effect instantly and, on a single-monitor machine, blanks your only display with no config file to reload from. Test monitor changes with a second display attached, or be ready to reach a TTY (Ctrl+Alt+F2) and run hyprctl -i 0 eval 'hl.monitor({ output = "eDP-1", disabled = false })'. hyprctl reload full-reset recreates the whole config context and should not be used unless genuinely necessary.
Symptom
Scripts, waybar modules, GUI display panels and copy-pasted one-liners that call hyprctl keyword monitor DP-1,disable or hyprctl keyword general:border_size 10 return no visible result and change nothing. Running it by hand appears to succeed. The error only shows on stderr, which most callers throw away: keyword can't work with non-legacy parsers. Use eval. The most reported instance is Omarchy's Display panel, where clicking a monitor row to disable or re-enable it does nothing at all.
Cause
hyprctl keyword drives the legacy hyprlang parser. Since 0.55 a hyprland.lua config uses the Lua config provider and the keyword path has nothing to write into, so the command changes nothing: on 0.55 the compositor answers keyword can't work with non-legacy parsers. Use eval., and on 0.56+ keyword is not a registered IPC command at all, so the answer is unknown request. The trap is the exit code, not the stream: hyprctl prints the compositor's reply on STDOUT and only returns non-zero when that reply starts with error:, and neither of these does, so the call exits 0. Anything that tests $? (a shell if, a Qt/Quickshell Process, a bar module) sees success, while a $(...) capture does receive the refusal text and usually discards it as uninteresting output. hyprctl dispatch has the same split: the classic hyprctl dispatch workspace 3 form is rejected and must be given as a Lua expression.
Fix
Keep every replacement command as written: hyprctl eval 'hl.monitor({ output = "DP-1", disabled = true })', hyprctl eval 'hl.config({ general = { border_size = 10 } })', hyprctl eval 'hl.workspace_rule({ workspace = "2", layout = "scrolling" })', hyprctl dispatch 'hl.dsp.focus({ workspace = "3" })', single quotes outside so the inner double quotes survive the shell. Two fixes.
- Check the result correctly. Unlike
keyword, a failinghyprctl evalDOES reply with a string startingerror:and hyprctl exits 7, so the exit code is trustworthy here, and the reply is on stdout, so2>&1is belt-and-braces rather than the point:
if ! out=$(hyprctl eval 'hl.config({ general = { border_size = 10 } })'); then
printf 'hyprctl eval failed: %s\n' "$out" >&2
fi
[ "$out" = "ok" ] || printf 'unexpected reply: %s\n' "$out" >&2
When auditing an old script, do not trust $? on the keyword call it is replacing: that one exits 0 while doing nothing.
- Enumerate options with
.name, not.value, becausehyprctl descriptionsentries are{name, description, default, current}:
hyprctl descriptions | jq -r '.[].name' | head # every option name
hyprctl descriptions | jq -r '.[] | "\(.name) = \(.current) (default \(.default))"' | head
hyprctl getoption general.border_size
hyprctl configerrors
Verify
hyprctl eval 'hl.config({ general = { border_size = 10 } })' prints ok and the change is visible immediately. hyprctl getoption general.border_size reports 10. hyprctl reload reverts it to your configured value.