Omarchy CLI 命令速查与安全使用指南

通过 omarchy commands、分组帮助和常用 update、theme、font、capture、agent、network、debug 命令发现当前可用功能。

omarchy CLI 是菜单和内部工具的命令入口，适合终端操作、可重复配置和 AI Agent 协作。命令会随版本扩展，因此“发现当前命令”比背诵一张永久表更重要。

从帮助开始

omarchy
omarchy commands
omarchy commands --all
omarchy <group> --help
omarchy <group> <command> --help

脚本集成可以查看当前版本是否支持 --json；自动化前还应检查命令退出码和幂等性，不能只解析面向人的彩色输出。

高频命令

目标	当前官方入口
更新系统	`omarchy update`
列出/应用主题	`omarchy theme list` / `omarchy theme set <name>`
列出字体	`omarchy font list`
截图	`omarchy screenshot`
调试信息	`omarchy debug`
设置默认 Agent	`omarchy default agent <name>`
给默认 Agent 任务	`omarchy agent prompt "..."`
安装/删除包	`omarchy pkg add <package>` / `omarchy pkg drop <package>`

不要把参数占位符连同尖括号照抄。例如 <name> 应换成帮助中列出的真实名称。

常用命令组

官方 CLI 当前包含但不限于：

agent：Agent 启动、用量与崩溃分析；
audio、bluetooth、brightness、network：硬件控制；
bar：顶栏布局与设置；
capture：截图、录屏、OCR、二维码；
channel：stable、RC、edge、dev 更新通道；
clipboard：剪贴板操作；
config：系统配置辅助；
debug：诊断和支持日志；
menu：从终端打开或定位菜单；
plugin：Shell 插件和顶栏组件；
theme、font：样式；
transcode：图片和视频转换。

精确子命令用帮助发现。例如：

omarchy capture --help
omarchy capture screenshot --help
omarchy network --help
omarchy bar --help

Capture 示例

omarchy capture screenshot region
omarchy capture screenshot fullscreen save
omarchy capture text
omarchy capture qr
omarchy transcode ~/Videos/demo.mov mp4 1080p

截图与 OCR 会把内容写入磁盘或剪贴板；在自动化中明确范围与保存模式，避免捕捉其他显示器或敏感窗口。

CLI 可以打开菜单根节点或指定页面：

omarchy menu
omarchy menu summon style.theme
omarchy menu close

顶栏配置示例：

omarchy bar position bottom
omarchy bar transparent toggle
omarchy bar defaults

bar defaults 会回到系统默认布局，运行前保存自定义 shell.json。

更新通道与系统命令

默认 stable 适合日常使用；edge、RC 和 dev 面向测试或开发。切换前阅读更新与恢复指南，并确认快照入口可用。

不要用 pacman -Syu 或 yay -Syu 绕过 Omarchy 更新流程。官方入口会把快照、迁移、配置与软件包更新放在一起。

给脚本和 Agent 的安全规则

先运行 --help 并保存当前版本；
只在明确目录执行，避免默认落到 $HOME；
不把密码、令牌和恢复密钥放进命令行参数；
修改前记录文件和 Git diff；
不自动确认磁盘、账户、引导和删除操作；
解析 JSON 或退出码，不依赖输出句子；
公开 debug 输出前脱敏。

旧版命令如 omarchy-reinstall 可能已经改为分组形式。需要恢复时先读快照与系统恢复。

来源：Omarchy CLI、Updates。