Omarchy CLI 完全指南：从终端与 AI Agent 操控 Omarchy 系统的命令中心

2026-09-08 23:34:39作者：尤峻淳Whitney

Omarchy 桌面环境日常由热键与 Super + Space 呼出的 Omarchy 菜单驱动，但同一套内部能力也全部暴露在 omarchy 命令行接口（CLI）上。本文围绕 manual/14-omarchy-cli.md 展开，结合 bin/ 目录下的真实实现，系统讲解命令的浏览方式、分组结构与路由原理、常用实操命令、菜单脚本化，以及面向 AI Agent 与开发者的机器可读输出。读完你既能在终端里熟练操控整个系统，也能理解新增命令与排查路由问题的底层机制。

为什么需要一个 Omarchy CLI

Omarchy 的系统控制入口主要有两套：一套是图形化的热键与 Omarchy 菜单（Super + Space），另一套就是 omarchy CLI。菜单适合人来点按，而 CLI 的价值在“可脚本化、可编程、可被 Agent 调用”——当你正带着一个 AI Agent 一起定制系统或排查问题时，把菜单里的每一项操作变成一条命令行指令，意味着 Agent 无需理解图形界面就能安全、精确地执行配置动作。

CLI 的覆盖面与内部工具完全一致：菜单里能做的主题切换、屏幕截图、菜单导航、系统更新等操作，背后都指向同一组命令，因此 CLI 不是一套被阉割的子集，而是"命令中心"的前台。在终端里直接输入 omarchy 即可看到全部可用能力。

命令中心初探：`omarchy` 主帮助

不带任何参数运行 omarchy，主分派器会输出"Omarchy command center"帮助页，内容包括调用方式、常用命令、命令分组与发现类子命令：

~ ❯ omarchy
Omarchy command center

Usage:
  omarchy <command> [args...]
  omarchy commands [--all] [--json] [--check]
  omarchy <group> --help
  omarchy <group> <command> --help

Common commands:
  omarchy update              Update Omarchy and system packages
  omarchy theme list          List available themes
  omarchy theme set <name>    Apply a theme
  omarchy font list           List available fonts
  omarchy screenshot          Take a screenshot
  omarchy debug               Print debugging information

需要留意 omarchy commands 这条特殊子命令：它是命令中心的"自省入口"，支持 --all（包含隐藏命令）、--json（输出机器可读的完整记录）、--markdown（输出 Markdown 表格）和 --check（校验命令元数据与路由冲突）。这与普通命令分派走了不同的处理路径（bin/omarchy 中的 parse_commands_args）。

主帮助中"Common commands"是高频命令的速查，而真正的能力地图在下方由 GROUP_DESCRIPTIONS 驱动的 Groups 列表中（见 bin/omarchy）。该列表是手工维护的说明表，每个分组名对应一句话描述；换言之，只要看到一个分组名，就能大致判断这一组命令的职责范围。

分组结构：几十个领域、几百条命令

命令中心按领域把命令组织成分组（group），以下摘自 bin/omarchy 的 GROUP_DESCRIPTIONS 声明，也是运行时主帮助的真实内容：

分组	描述	分组	描述
`agent`	AI coding agent usage data	`menu`	Omarchy menu commands
`audio`	Audio input and output controls	`monitor`	Monitor status helpers
`bar`	Omarchy shell bar layout and settings	`network`	Network status helpers
`battery`	Battery status helpers	`osd`	On-screen display status helpers
`bluetooth`	Bluetooth device controls	`plugin`	Shell plugin / bar widget management
`branch`	Omarchy git branch management	`powerprofiles`	Power profile management
`branding`	About and screensaver branding	`reminder`	Desktop notification reminders
`brightness`	Display and keyboard brightness	`restart`	Restart Omarchy components
`capture`	Screenshots and screen recording	`setup`	Interactive setup wizards
`channel`	Release channel management	`shell`	Omarchy shell IPC helpers
`clipboard`	Clipboard helpers	`snapshot`	System snapshots
`config`	System configuration helpers	`system`	Status, reboot, shutdown, logout, lock
`debug`	Diagnostics and support logs	`theme`	Theme management
`display`	Display and text scaling	`toggle`	Toggle Omarchy features
`font`	Font management	`update`	Omarchy and system updates
`hw`	Hardware detection and controls	`version`	Version and channel information
`hyprland`	Hyprland window/monitor/toggle controls	`webapp`	Web app launchers
`install`	Optional software installers	`windows`	Windows VM management

注意有些分组的命名刻意用了“动词”——例如 restart、install、remove、setup、refresh、toggle——这让命令路径读起来像自然语言短语（omarchy restart shell、omarchy toggle nightlight），对终端用户和 AI Agent 都更友好。

进入一个分组同样简单：输入 omarchy <group> 或 omarchy <group> --help 都会展开该组内全部命令及其用法。例如：

~ ❯ omarchy capture
Capture commands — Screenshots and screen recording:
  omarchy capture qr                                                                                                                                                                                                       Decode a QR code from a screenshot region
  omarchy capture screenrecording [--fullscreen] [--with-desktop-audio] [--with-microphone-audio] [--with-webcam] [--webcam-device=<device>] [--webcam-size=<small|medium|large>] [--resolution=<size>] [--stop-recording]  Start or stop screen recording
  omarchy capture screenrecording with webcam                                                                                                                                                                              Pick a webcam and start a screen recording with it
  omarchy capture screenshot [smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>]                                                                                                                         Take a screenshot
  omarchy capture text                                                                                                                                                                                                     Extract text from a screenshot region with OCR
  omarchy capture webcam resize <smaller|larger|reset|small|medium|large>                                                                                                                                                  Resize the active webcam recording overlay

这一行行“命令 + 参数 + 描述”并非写死在某个帮助文件里，而是由路由层根据每个命令文件头部声明的元数据实时合成的（详见下文"路由与元数据"一节）。分组列表在这里是动态聚合：任何新增的可执行命令都会自动出现在所属组下。

全局 `--help`：任何一层都能问

命令中心贯彻"处处可问帮助"的设计——无论是整组还是单条命令：

omarchy capture --help              # 组的帮助
omarchy capture screenshot --help   # 单条命令的帮助
omarchy screenshot --help           # 别名或普通路径同样适用

单条命令的帮助比分组列表更详细，包含 Usage、说明、Arguments、Examples、Aliases、Binary 以及（当文件名路由与规范路由不一致时的）Filename route 和 Related commands。例如对截图命令执行 omarchy screenshot --help 时，你能看到它的实际二进制是 omarchy-capture-screenshot，别名 omarchy screenshot 指向的是 omarchy capture screenshot。

需要给 AI Agent 提供结构化信息时，还可以在 --help 后追加 --json：路由层会把该命令的完整 JSON 记录（route、binary、group、name、summary、args、examples、aliases 等字段）打印出来（见 bin/omarchy）。这等价于 omarchy <route> --help --json。

路由与元数据：无注册表的命令中心是如何工作的

Omarchy CLI 的核心设计是 “文件名即路由、头部注释即元数据”，这一点在 docs/cli-router.md 中有完整阐述，也直接决定了你该怎么使用与扩展这套 CLI。

扁平的 `omarchy-*` 可执行文件命名空间

bin/ 目录下没有集中式命令注册表。每一个可执行的 bin/omarchy-* 文件本身就是一条命令，bin/omarchy 负责把空格分隔的命令行映射到这一堆扁平文件上：

omarchy theme set foo  →  exec bin/omarchy-theme-set foo

文件名中 omarchy- 之后的部分按第一个连字符拆分出分组与名字：omarchy-theme-set → 分组 theme、名字 set；omarchy-hw-asus-rog → 分组 hw、名字 asus rog（剩余连字符转空格）；单一词干如 omarchy-update 则是该组自身的根命令。

头部 `omarchy:` 元数据注释

命令文件会通过靠近文件顶部的注释行声明帮助与路由信息，格式与键名记录在 agents/skills/command-metadata.md：

# omarchy:group=... —— 覆盖由文件名推断出的分组；
# omarchy:name=... —— 覆盖由文件名推断出的命令名（置空可让该命令成为分组的根命令）；
# omarchy:summary=... —— 帮助里的简短描述；
# omarchy:args=... —— 用法中的参数说明；
# omarchy:examples=... —— 以 | 分隔的示例；
# omarchy:alias=... / # omarchy:aliases=... —— 额外可用的路由；
# omarchy:hidden=true —— 从默认命令列表中隐藏（路由与调用不受影响，适合安装期管道等内部工具）；
# omarchy:requires-sudo=true —— 标记需要 sudo 的命令。

真实例子（bin/omarchy-capture-screenshot）：

# omarchy:summary=Take a screenshot
# omarchy:group=capture
# omarchy:args=[smart|region|windows|fullscreen] [slurp|copy|save] [--editor=<name>]
# omarchy:examples=omarchy screenshot | omarchy capture screenshot region
# omarchy:aliases=omarchy screenshot

注意别把 omarchy:examples 当成显示用示例的必需品：只有当参数需要解释时才用。路由层解析头部时只扫描前 80 行（bin/omarchy 中 METADATA_SCAN_LIMIT=80），遇到第一条非注释行即停止；格式错误的 omarchy: 行与未知键会被静默忽略，而不是让路由器崩溃——一个拼写错误最多让命令退化回文件名路由。

最长前缀匹配与两条分派路径

路由解析采用最长前缀匹配：路由器先尝试把整个参数列表当作一条路由，匹配不上就逐个丢弃尾部单词，直到命中为止，被丢弃的部分原样传给目标二进制。分派分两条路径：

快路径（fast path）：把参数前缀用连字符拼起来直接探测可执行文件是否存在（bin/omarchy 的 dispatch_fast_or_help）。omarchy theme set foo 会依次探测 omarchy-theme-set-foo、omarchy-theme-set，命中即 exec。这样普通调用只做几次文件系统 stat，完全不用读取几百个文件的元数据头——元数据仅在需要帮助时才惰性加载。这正是 docs/cli-router.md 中提到 omarchy dev benchmark cli 追踪的那部分延迟被优化的原因。
元数据回退：当快路径找不到文件（比如被元数据移动过的路由 omarchy share，或别名 omarchy screenshot），路由器才加载全部元数据，按注册的路由表做同样的最长前缀解析（bin/omarchy 的 resolve_route、bin/omarchy 的 dispatch_or_help）。

分派最终用 exec 替换当前进程：子命令只看到被丢弃的剩余参数，退出码也是子命令自己的；未知命令或二进制缺失时路由器以 127 退出，并输出"did you mean …"建议与 omarchy commands --all 提示。

两条路由：规范路由与文件名路由

每条命令会注册两条路由：元数据覆盖后的规范路由 omarchy <group> <name>，以及把文件名里所有连字符转成空格的"文件名路由"。二者相同的情况最常见；不同时两者同时生效。例如 bin/omarchy-install-gaming-xbox-cloud 用 # omarchy:name=gaming xbox-cloud 保留名字里的连字符，于是 omarchy install gaming xbox-cloud 是规范路由，而 omarchy install gaming xbox cloud（文件名路由）照样能解析。

当两条路由同时指向不同二进制时会产生路由碰撞：先注册者生效，分派不受影响，但冲突会被记录，供 omarchy commands --check 报告。

高频实操命令解析

主题与字体：`theme`、`font`

主题操作是 Omarchy CLI 最常用的场景之一，由三条命令闭环：

omarchy theme list              # 列出可用主题
omarchy theme set <name>        # 应用主题，如 omarchy theme set "Tokyo Night"
omarchy theme current           # 查看当前主题

omarchy theme set 的底层实现（bin/omarchy-theme-set）说明了主题系统的一角：它会同时处理系统主题、Hyprland 配置、背景图过渡缓存以及用户级主题目录（~/.config/omarchy/themes 与 $OMARCHY_PATH/themes）。对来自 git 仓库安装的主题，脚本还会刻意不落地部分会执行代码的文件（如 alacritty.toml、foot.ini、kitty.conf、vscode.json、各 .lua），理由是这些文件中的内容会被终端/编辑器当作程序或任意 JavaScript 加载——这是主题安全模型的一部分，测试 test/shell.d/theme-staging-test.sh 会校验生成的每个主题文件要么被此名单拒绝、要么被记录为纯颜色文件。

字体命令同构：omarchy font list 列出可用字体、omarchy font set <name> 应用、omarchy font current 查看当前项。

截图与录屏：`capture` 组

文档 Common commands 里的 omarchy screenshot 实际是截图子命令的别名，规范路径在 capture 组内。参考上面 omarchy capture 的组列表：

omarchy capture screenshot smart                 # 智能选区截图（默认 slurp 处理流程）
omarchy capture screenshot region copy           # 框选并把结果复制到剪贴板
omarchy capture screenshot fullscreen save       # 全屏并保存到文件
omarchy capture screenshot --editor=editor名       # 截图后交给指定编辑器
omarchy capture text                             # 对截图区域做 OCR 提取文本
omarchy capture qr                               # 解码截图区域中的二维码
omarchy capture screenrecording [可选参数]        # 启动/停止录屏

这些都不是包装图形工具那么简单。以 omarchy capture screenshot 为例，源码展示了它如何协调底层组件（bin/omarchy-capture-screenshot）：

输出目录取自 OMARCHY_SCREENSHOT_DIR，其次 XDG_PICTURES_DIR，最后 $HOME/Pictures，目录不存在时自动创建并通过通知提示；
截图编辑器可由 OMARCHY_SCREENSHOT_EDITOR 环境变量或 --editor=<name> 参数指定，默认 tensaku-edit；
它调用 omarchy-capture-region 完成选区（含 --keep-freeze 冻结画面模式），并在 grim 抓帧前强制启用硬件光标、退出时恢复，以保证截图内容稳定、光标被正确烘焙进画面。

系统更新与诊断：`update`、`debug`

omarchy update     # 更新 Omarchy 本体与系统包
omarchy debug      # 打印调试信息

update 在 bin/ 下同样以子命令树的形式展开（omarchy-update、omarchy-update-aur-pkgs、omarchy-update-system-pkgs、omarchy-update-firmware、omarchy-update-dev、omarchy-update-lock 等），对应 docs/update-process.md 描述的更新流程。omarchy debug 的输出面向诊断与支持日志场景，适合在提问或报 Bug 前收集系统状态。

其他常用组合速览

omarchy state                     # 查看系统状态
omarchy system reboot|shutdown|logout|lock   # 电源与会话控制
omarchy restart shell             # 重启 Omarchy shell
omarchy toggle nightlight         # 切换夜间护眼
omarchy theme bg next             # 切换下一张壁纸
omarchy menu                      # 打开 Omarchy 菜单（见下节）

组合规律很好记：omarchy <动词或领域> <对象> [参数]，几乎每个日常操作都能拼出来。

用 `omarchy menu` 从终端脚本化菜单

Omarchy 菜单本身也可以脚本化，这对自定义键绑定尤其有用（详见 manual/14-omarchy-cli.md）：

omarchy menu                          # 在根节点打开菜单
omarchy menu summon style.theme       # 直接跳到主题选择器
omarchy menu toggle system            # 打开系统菜单；若已打开则关闭
omarchy menu close                    # 收起菜单
omarchy menu refresh                  # 重新解析菜单配置

omarchy menu 的默认动词是 toggle，默认路由是 root；summon 则“总是打开”（不做已开即关的切换）。路由参数（如 style.theme）表达的是菜单树中的导航路径，让 Agent 能一步直达指定面板。

从源码看，菜单命令是菜单插件 IPC 的薄封装（bin/omarchy-menu）：菜单本身是 Omarchy shell 的一等插件 omarchy.menu，菜单路由以 JSON payload 的形式传给 omarchy-shell shell toggle/summon/hide omarchy.menu，而菜单的静态结构定义在 default/omarchy/omarchy-menu.jsonc（JSONC 格式，允许注释）。因此“终端开菜单”与你按 Super + Space 打开的是同一个菜单实例与同一套配置。菜单结构整体由 docs/menu.md 描述。

面向 AI Agent 与开发者：机器可读的自省接口

如果你在终端带着 AI Agent 工作，或想用脚本消费命令中心信息，自省子命令是最直接的入口：

omarchy commands                # 列出全部非隐藏命令及其描述
omarchy commands --all          # 额外包含标记为 hidden 的命令
omarchy commands --markdown     # 输出 Markdown 命令表（含 Command/Binary/Summary 三列）
omarchy commands --json         # 输出机器可读的完整 JSON 记录
omarchy commands --check        # 校验命令元数据与路由

--json 输出的每条记录包含：route（规范路由）、binary、group、name、summary、requires_sudo、hidden、args、examples（数组）、aliases（数组）、filename_route、以及 routes（所有能解析到该二进制的路由并集），外层以 { ok: true, commands: [...] } 包装（见 bin/omarchy）。这套 schema 是 Agent 理解系统能力边界的可靠依据。