Hyprland hyprctl 手册深度解析通过 CLI 与脚本远程控制合成器【免费下载链接】HyprlandHyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesnt sacrifice on its looks.项目地址: https://gitcode.com/GitHub_Trending/hy/Hyprland本文以 Hyprland 官方 man 手册docs/hyprctl.1.rst为核心系统讲解 hyprctl 这一 CLI 工具的全部控制命令、信息查询命令与选项用法并结合 hyprctl 客户端源码、服务端 IPC 实现 与 补全定义文件 深入说明其 Unix Socket 通信机制、实例选择逻辑与退出码约定帮助你在脚本和自动化场景中对 Hyprland 进行可靠的程序化控制。一、hyprctl 是什么定位与调用方式hyprctl 官方手册hyprctl.1.rst对它的定义非常简洁hyprctl 是一个用于从命令行或脚本控制合成器部分功能的工具。它与 Hyprland 合成器进程解耦运行在用户 shell 中通过 IPC 通道向合成器下发指令并读取状态。手册给出的调用格式SYNOPSIS为hyprctl [flags] command [args]flags可选标志如-jJSON 输出、--batch批量执行等完整清单见手册 OPTIONS 小节及 Strings.hpp 中内置的USAGE帮助文本command要执行的命令分为控制类CONTROL COMMANDS与信息类INFO COMMANDS两大类args命令所需参数部分命令没有参数时该位置可以填任意内容。1.1 通信机制Unix Socket 与实例签名从源码结构看hyprctl 与合成器之间通过Unix Domain Socket通信这是理解所有命令行为的前提。客户端侧hyprctl/src/main.cpp运行时目录默认为$XDG_RUNTIME_DIR/hypr若该环境变量未设置则回退到/run/user/uid/hypr见getRuntimeDir()L87-L94连接目标实例由环境变量HYPRLAND_INSTANCE_SIGNATURE决定socket 路径为运行时目录/实例签名/.socket.sockL231-L241若该变量未设置hyprctl 会直接报错HYPRLAND_INSTANCE_SIGNATURE was not set! (Is Hyprland running?)——这是最常见的“找不到 Hyprland”错误来源通常意味着当前 shell 不在 Hyprland 会话内。服务端侧src/ipc/s1/Unix.cpp合成器在自身的实例目录下绑定同一个.socket.sock路径由 src/ipc/s1/S1.cpp 中的CSocket1完成请求解析与命令分发。请求串以[j]、[r]、[a]、[f]等单字母前缀携带输出格式与行为标志JSON、刷新状态、含全部输出、跟随模式随后是命令名与参数例如j/monitors、r/dispatch workspace 2。客户端在发起请求时会先统计请求中的空格数做参数下限校验request()中的minArgs检查并设置 5 秒接收超时高负载下服务端可能出现分段写入客户端会持续读取直到服务端关闭连接再拼出完整回复L255-L275保证批量或大输出场景下回复不被截断。二、控制命令CONTROL COMMANDS手册将控制类命令归纳为 5 个它们负责“改变合成器的状态或行为”共同约定成功时返回ok失败时返回错误信息。2.1 dispatch调用调度器hyprctl dispatch hl.dsp.exec_cmd(kitty) hyprctl dispatch hl.dsp.window.close()dispatch用于以参数调用一个 dispatcher快捷键调度器等价于在配置里触发对应的 keybind 动作。必须提供参数对无参数的调度器参数内容可以是任意值。手册中的示例展示了 Lua 风格的调度器写法hl.dsp.*说明在 Lua 配置提供方下调度器同样可以以表达式形式下发。完整的调度器清单可以在 补全定义文件 的DISPATCHERS部分查到涵盖常用类别类别调度器示例说明执行与按键转发exec、execr、pass、sendshortcut、sendkeystate执行 shell 命令、向窗口转发按键窗口管理killactive、closewindow、togglefloating、setfloating、settiled、fullscreen、fullscreenstate、pin、centerwindow关闭、浮动/平铺、全屏、固定、居中工作区workspace、movetoworkspace、movetoworkspacesilent、renameworkspace、movecurrentworkspacetomonitor、swapactiveworkspaces、togglespecialworkspace切换、移动、重命名、跨屏移动工作区焦点与布局movefocus、movewindow、swapwindow、cyclenext、swapnext、resizeactive、moveactive、resizewindowpixel、movewindowpixel、splitratio方向移动、交换、调整大小与分割比例组grouptogglegroup、changegroupactive、lockgroups、moveintogroup、moveoutofgroup、movegroupwindow、denywindowfromgroup分组、组内切换、锁定组其他submap、exit、forcerendererreload、dpms、event、global、focusurgentorlast、focuscurrentorlast、tagwindow、focuswindow、focusmonitor、toggleopaque、movecursor、movecursortocorner、alterzorder、fakefullscreen子键位映射、退出、渲染器重载、DPMS、socket2 自定义事件、全局快捷键等例如脚本中常用hyprctl dispatch workspace 2切到 2 号工作区hyprctl dispatch killactive关闭当前窗口。2.2 keyword动态设置配置项hyprctl keyword bind SUPER,0,pseudo hyprctl keyword general:border_size 10keyword用于动态设置一个配置关键词语法与在配置文件hyprland.lua/ 传统hyprland.conf中书写一致keyword 关键词 值。它不修改配置文件只改变运行时的配置状态。手册明确提示当你的配置提供方是 Lua 时此命令不生效应改用下面的eval。这是因为 Lua 配置由脚本重建直接改写传统配置树会破坏 Lua 侧的视图一致性。从源码看keyword在服务端对应前缀匹配COMMAND_MATCH_PREFIX注册的命令见 src/ipc/s1/Commands.cpp 的registerBuiltinCommands客户端要求请求中至少含 2 个空格分隔的参数request(fullRequest, 2)hyprctl/src/main.cpp L559-L560即keyword、名称、值三者缺一不可。2.3 eval动态执行 Lua 表达式hyprctl eval hl.bind(SUPER SHIFT Q, hl.dsp.exec_cmd(firefox)) hyprctl eval hl.config({ general { border_size 10 } })eval在使用 Lua 配置提供方时动态求值任意 Lua 表达式可以访问hl.*API上例分别是运行时注册一个快捷键、以及修改general.border_size配置。dispatch示例中的hl.dsp.exec_cmd(kitty)、hl.dsp.window.close()正是通过调度器执行 Lua 表达式的写法。除一次性eval外USAGE 帮助 中还提供了repl [code]不带代码时进入交互式 Lua REPL^D退出支持 readline 历史与多行续行见 main.cpp L569-L597带代码时则单次执行并打印结果——对调试 Lua 配置非常实用。2.4 reload强制重载配置hyprctl reload强制重新加载配置文件。USAGE 帮助 说明其支持可选参数config-onlyhyprctl reload config-only仅重载配置而跳过显示器monitor重载适合只想应用配置改动、不希望触发热插拔流程的场景。服务端侧该命令按前缀匹配注册Commands.cpp L1965因此可以透传后续参数。2.5 kill点击杀窗模式hyprctl kill进入 kill mode移动鼠标点击任意应用即可将其关闭按ESCAPE退出该模式。它与dispatch killactive的区别在于目标由鼠标点选决定无需窗口处于聚焦状态。三、信息命令INFO COMMANDS手册列出的信息命令用于读取合成器当前状态输出为人类可读文本配合-j可得到 JSON。以下先完整覆盖手册所列 9 个命令再结合 USAGE 帮助文本 补齐当前版本实际可用的更多命令。3.1 手册覆盖的 9 个命令命令手册描述用途version打印 Hyprland 版本、编译 flags、commit 与分支故障排查、版本确认monitors列出所有输出及其属性查看分辨率、缩放、方向等USAGE 补充monitors all会同时列出非激活输出workspaces列出所有工作区及其属性查看工作区占用、焦点、全屏等状态clients列出所有窗口及其属性脚本常配合awk提取class、title字段devices列出所有已连接输入设备键盘、鼠标等设备名可用于switchxkblayoutactivewindow返回当前活动窗口名状态栏、窗口监控常用layers列出所有 layer层级表面查看 layer-shell 面板、状态栏等splash返回当前随机欢迎语splash纯展示性输出status返回内部状态信息如配置格式、后端判断当前配置提供方传统/Lua与后端类型3.2 当前版本中的扩展命令从 Strings.hpp 的完整 USAGE 帮助文本看实际可用信息命令比手册更全常用的包括activeworkspace活动工作区及属性与workspaces互补animations当前动画与贝塞尔曲线配置binds所有已注册的快捷键绑定configerrors当前所有配置解析错误排错配置时非常有用cursorpos光标在全局布局坐标下的位置descriptions输出包含全部配置项、描述、值类型与取值范围的可解析 JSON是程序化读取配置元信息的入口服务端直接调用Config::Values::getAsJson()见 Commands.cpp L1905-L1907getoption option读取某个配置项的当前值globalshortcuts所有全局快捷键配合 globalshortcuts portalinstances列出所有运行中的 Hyprland 实例签名、时间戳、PID、Wayland socket该命令不依赖 HYPRLAND_INSTANCE_SIGNATURE多实例环境的管理入口layouts列出所有可用布局含插件提供的布局systeminfo系统信息可附带配置内容workspacerules已定义的工作区规则列表decorations window_regex、setprop/getprop窗口装饰与属性读写setprop支持可选的lock参数防止被动态 windowrule 覆盖见 SETPROP_HELP。此外还有交互/输出类子命令hyprpaper壁纸、hyprsunset色温、plugin插件 load/unload/list、notify内置通知、output创建/移除虚拟输出、switchxkblayout、setcursor、seterror、rollinglog支持-f/--follow跟踪日志等各自的子命令说明由hyprctl cmd --help输出对应的帮助文本main.cpp L446-L467例如 OUTPUT_HELP 说明了output create wayland|x11|headless|auto与output remove name的用法。3.3 服务端的命令注册模型从源码结构看信息命令与控制命令在服务端统一注册进CSocket1的命令表Commands.cpp L1936-L1978 中每个命令由SCommand{name, match, handler}描述match区分精确匹配如workspaces与前缀匹配如monitors、dispatch、eval、reload前缀匹配用于透传命令的后续参数handler 接收解析后的SRequest含格式、刷新标志、是否包含非活动输出等返回文本或 JSON 回复。这一注册模型也意味着插件可以注册自己的 IPC 命令如plugin、hyprpaper通道扩展 hyprctl 的能力边界。四、选项OPTIONS4.1 -jJSON 输出hyprctl -j clients-j让信息类命令以 JSON 输出是脚本解析状态数据的标准方式。在 main.cpp L421-L423 中-j会转换为请求前缀中的j标志随请求发送服务端据此切换FORMAT_JSON输出格式见 S1.hpp 的 eOutputFormat。4.2 --batch批量执行命令hyprctl --batch keyword general:border_size 2 ; keyword general:gaps_out 20--batch指定一批要执行的命令命令之间用;分隔。其底层实现在 batchRequest()客户端将命令串加上[[BATCH]]标记后整体发送由服务端统一调度执行当同时使用-j时客户端还会在每条命令前插入j/前缀使批次内每条子命令都以 JSON 格式回复。批量执行适合需要原子性地连续修改多项配置的场景避免多次 socket 往返。4.3 手册未覆盖、但源码确认的其他选项USAGE 帮助 与 hyprctl.usage 共同确认了更完整的选项集合选项作用-i / --instance sig\|index指定目标实例可以是完整签名也可以是hyprctl instances列表中的序号0、1、…源码在 main.cpp L501-L528 中实现含下划线的参数按签名处理纯数字按实例索引查找-r命令下发后刷新状态用于更新变量类状态-q / --quiet禁用 hyprctl 输出配合-i做静默检测等-f / --follow仅rollinglog支持持续跟踪日志客户端进入rollingRead()循环读取直至 SIGINTmain.cpp L174-L203-h / --help打印帮助对notify、output、plugin、setprop等带子命令的项会打印各自的专项帮助使用多实例如多用户或多会话并行运行 Hyprland时instances-i的组合是唯一可靠地跨实例定位的手段。五、返回值与退出码编写健壮脚本的依据手册约定控制命令“成功返回ok失败返回错误信息”。从 request() 的实现看hyprctl 的进程退出码同样有明确语义脚本可直接据此分支退出码含义0成功回复正常返回1无法创建 socket / 参数错误如打印 USAGE 后返回2无法设置 socket 超时 / 缺少实例签名部分路径3HYPRLAND_INSTANCE_SIGNATURE未设置——Hyprland 未运行或 shell 不在其会话内4无法连接目标 socket 路径5向 socket 写入失败rollingRead路径下表示读取失败6读取回复失败含 5 秒超时未收到 IPC 响应7服务端回复以error:开头即业务层面失败8仅交互式 Lua REPL检测到行未完成的语法错误提示用于多行续行由此典型的脚本健壮性写法是先判断退出码是否为 3/4连接性问题再判断 7业务错误最后解析 stdout 中的ok/error文本。六、Shell 补全与配套资源仓库为 hyprctl 提供了三种 Shell 的补全脚本hyprctl.bash、hyprctl.fish、hyprctl.zsh它们由 hyprctl.usage 经 complgen 工具生成文件头注释给出了再生成命令。该 usage 文件同时是理解 hyprctl 参数空间的一份机器可读清单ARGUMENTS枚举全部命令、DISPATCHERS枚举全部调度器、NOTIFICATION_TYPES与PROPS分别约束notify图标编号与setprop可写属性WINDOWS、MONITORS、KEYBOARDS等还定义了动态补全来源例如窗口类名来自hyprctl clients输出可见 hyprctl 的输出本身就是后续命令补全的数据源二者天然构成闭环。测试侧hyprtester 目录下的 hyprctlCompat.cpp 提供了与 hyprctl 兼容的测试通道用于自动化测试中模拟对合成器的 hyprctl 式调用进一步印证了上述“请求前缀 Unix socket”协议是 Hyprland 自身测试体系也依赖的稳定接口。七、手册元信息与延伸阅读按 hyprctl.1.rst 的原始声明名称hyprctl——Utility for controlling parts of Hyprland from a CLI or a scriptBug 报告面向在线 issue 渠道提交手册指向上游 issue 跟踪版权Copyright (c) 2022, vaxerski配套文件同名 roff 手册页 docs/hyprctl.1 由 Pandoc 自动生成的 man 页面内容与 RST 源一致安装后可直接man hyprctl查阅。关键源码索引主题路径客户端入口、参数解析、socket 通信hyprctl/src/main.cpp完整 USAGE 与各子命令帮助文本hyprctl/src/Strings.hpp补全/命令与调度器枚举清单hyprctl/hyprctl.usage服务端命令注册与处理src/ipc/s1/Commands.cpp服务端 socket 绑定src/ipc/s1/Unix.cpp请求/响应与命令模型src/ipc/s1/S1.hpp适用前提与限制以上行为均以当前仓库版本的源码与手册为准keyword/eval的可用性取决于当前配置提供方传统配置或 Lua 配置monitors all、repl、descriptions等扩展命令以实际运行的 Hyprland 构建版本支持为准可通过hyprctl --help现场确认。【免费下载链接】HyprlandHyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesnt sacrifice on its looks.项目地址: https://gitcode.com/GitHub_Trending/hy/Hyprland创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考