ZacharyZhang-NY/omarchycn
4
5
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 5 Wiki Activity

Update to use the new single command cli

Browse Source
This commit is contained in:
David Heinemeier Hansson
2026-05-01 18:04:42 +02:00
parent d2a4cc0c4d
commit 91d43d3316
1 changed files with 73 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
default/omarchy-skill/SKILL.md
+73 -65
View File
@@ -8,7 +8,7 @@ description: >
monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes, monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes,
wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace
settings, display config, and user-facing omarchy commands. Excludes Omarchy settings, display config, and user-facing omarchy commands. Excludes Omarchy
source development in ~/.local/share/omarchy/ and omarchy-dev-* workflows. source development in ~/.local/share/omarchy/ and `omarchy dev` workflows.
--- ---
# Omarchy Skill # Omarchy Skill
@@ -29,19 +29,19 @@ It is not for contributing to Omarchy source code.
- Window behavior, animations, opacity, blur, gaps, borders - Window behavior, animations, opacity, blur, gaps, borders
- Layer rules, workspace settings, display/monitor configuration - Layer rules, workspace settings, display/monitor configuration
- Themes, wallpapers, fonts, appearance changes - Themes, wallpapers, fonts, appearance changes
- User-facing `omarchy-*` commands (`omarchy-theme-*`, `omarchy-refresh-*`, `omarchy-restart-*`, etc.) - User-facing `omarchy` commands (`omarchy theme ...`, `omarchy refresh ...`, `omarchy restart ...`, etc.)
- Screenshots, screen recording, night light, idle behavior, lock screen - Screenshots, screen recording, night light, idle behavior, lock screen
**If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.** **If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.**
**Do NOT use this skill for Omarchy development tasks** (editing files in `~/.local/share/omarchy/`, creating migrations, or running `omarchy-dev-*` workflows). **Do NOT use this skill for Omarchy development tasks** (editing files in `~/.local/share/omarchy/`, creating migrations, or running `omarchy dev ...` workflows).
## Critical Safety Rules ## Critical Safety Rules
**For end-user customization tasks, NEVER modify anything in `~/.local/share/omarchy/`** - but READING is safe and encouraged. **For end-user customization tasks, NEVER modify anything in `~/.local/share/omarchy/`** - but READING is safe and encouraged.
This directory contains Omarchy's source files managed by git. Any changes will be: This directory contains Omarchy's source files managed by git. Any changes will be:
- Lost on next `omarchy-update` - Lost on next `omarchy update`
- Cause conflicts with upstream - Cause conflicts with upstream
- Break the system's update mechanism - Break the system's update mechanism
@@ -56,7 +56,7 @@ This directory contains Omarchy's source files managed by git. Any changes will
``` ```
**Reading `~/.local/share/omarchy/` is SAFE and useful** - do it freely to: **Reading `~/.local/share/omarchy/` is SAFE and useful** - do it freely to:
- Understand how omarchy commands work: `cat $(which omarchy-theme-set)` - Understand how omarchy commands work: `omarchy theme set --help` or `cat $(which omarchy-theme-set)`
- See default configs before customizing: `cat ~/.local/share/omarchy/config/waybar/config.jsonc` - See default configs before customizing: `cat ~/.local/share/omarchy/config/waybar/config.jsonc`
- Check stock theme files to copy for customization - Check stock theme files to copy for customization
- Reference default hyprland settings: `cat ~/.local/share/omarchy/default/hypr/*` - Reference default hyprland settings: `cat ~/.local/share/omarchy/default/hypr/*`
@@ -84,34 +84,43 @@ Omarchy is built on:
## Command Discovery ## Command Discovery
Omarchy provides ~145 commands following `omarchy-<category>-<action>` pattern. Omarchy ships a single `omarchy` CLI that dispatches to all `omarchy-*` binaries via `omarchy <group> <action>`. Always prefer this form — it is self-documenting and stable. The underlying `omarchy-*` binaries still exist on `PATH` and remain safe to read for source.
```bash ```bash
# List all omarchy commands # List every documented command and its summary
compgen -c | grep -E '^omarchy-' | sort -u omarchy commands
# Find commands by category # Show the commands inside a group
compgen -c | grep -E '^omarchy-theme' omarchy theme --help
compgen -c | grep -E '^omarchy-restart' omarchy refresh --help
omarchy restart --help
# Show help for a specific command (does not execute it)
omarchy theme set --help
# Machine-readable listing (binary, route, summary, args, aliases)
omarchy commands --json
# Read a command's source to understand it # Read a command's source to understand it
cat $(which omarchy-theme-set) cat $(which omarchy-theme-set)
``` ```
### Command Categories ### Command Groups
| Prefix | Purpose | Example | Run `omarchy --help` for the full list. The most common groups:
|--------|---------|---------|
| `omarchy-refresh-*` | Reset config to defaults (backs up first) | `omarchy-refresh-waybar` | | Group | Purpose | Example |
| `omarchy-restart-*` | Restart a service/app | `omarchy-restart-waybar` | |-------|---------|---------|
| `omarchy-toggle-*` | Toggle feature on/off | `omarchy-toggle-nightlight` | | `omarchy refresh` | Reset config to defaults (backs up first) | `omarchy refresh waybar` |
| `omarchy-theme-*` | Theme management | `omarchy-theme-set <name>` | | `omarchy restart` | Restart a service/app | `omarchy restart waybar` |
| `omarchy-install-*` | Install optional software | `omarchy-install-docker-dbs` | | `omarchy toggle` | Toggle feature on/off | `omarchy toggle nightlight` |
| `omarchy-launch-*` | Launch apps | `omarchy-launch-browser` | | `omarchy theme` | Theme management | `omarchy theme set <name>` |
| `omarchy-capture-*` | Screenshots and recordings | `omarchy-capture-screenshot` | | `omarchy install` | Install optional software / packages | `omarchy install docker dbs` |
| `omarchy-pkg-*` | Package management | `omarchy-pkg-install <pkg>` | | `omarchy launch` | Launch apps | `omarchy launch browser` |
| `omarchy-setup-*` | Initial setup tasks | `omarchy-setup-fingerprint` | | `omarchy capture` | Screenshots and recordings | `omarchy capture screenshot` |
| `omarchy-update-*` | System updates | `omarchy-update` | | `omarchy pkg` | Package management | `omarchy pkg install <pkg>` |
| `omarchy setup` | Initial setup tasks | `omarchy setup fingerprint` |
| `omarchy update` | System updates | `omarchy update` |
## Configuration Locations ## Configuration Locations
@@ -134,7 +143,7 @@ cat $(which omarchy-theme-set)
**Key behaviors:** **Key behaviors:**
- Hyprland auto-reloads on config save (no restart needed for most changes) - Hyprland auto-reloads on config save (no restart needed for most changes)
- Use `hyprctl reload` to force reload - Use `hyprctl reload` to force reload
- Use `omarchy-refresh-hyprland` to reset to defaults - Use `omarchy refresh hyprland` to reset to defaults
### Waybar (Status Bar) ### Waybar (Status Bar)
@@ -144,9 +153,9 @@ cat $(which omarchy-theme-set)
└── style.css # Styling └── style.css # Styling
``` ```
**Waybar does NOT auto-reload.** You MUST run `omarchy-restart-waybar` after any config changes. **Waybar does NOT auto-reload.** You MUST run `omarchy restart waybar` after any config changes.
**Commands:** `omarchy-restart-waybar`, `omarchy-refresh-waybar`, `omarchy-toggle-waybar` **Commands:** `omarchy restart waybar`, `omarchy refresh waybar`, `omarchy toggle waybar`
### Terminals ### Terminals
@@ -156,7 +165,7 @@ cat $(which omarchy-theme-set)
~/.config/ghostty/config ~/.config/ghostty/config
``` ```
**Command:** `omarchy-restart-terminal` **Command:** `omarchy restart terminal`
### Other Configs ### Other Configs
@@ -186,9 +195,9 @@ cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)
# 4. Apply changes # 4. Apply changes
# - Hyprland: auto-reloads on save (no restart needed) # - Hyprland: auto-reloads on save (no restart needed)
# - Waybar: MUST restart with omarchy-restart-waybar # - Waybar: MUST restart with `omarchy restart waybar`
# - Walker: MUST restart with omarchy-restart-walker # - Walker: MUST restart with `omarchy restart walker`
# - Terminals: MUST restart with omarchy-restart-terminal # - Terminals: MUST restart with `omarchy restart terminal`
``` ```
### Pattern 2: Make a new theme ### Pattern 2: Make a new theme
@@ -196,7 +205,7 @@ cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)
1. Create a directory under ~/.config/omarchy/themes. 1. Create a directory under ~/.config/omarchy/themes.
2. See how an existing theme is done via ~/.local/share/omarchy/themes/catppuccin. 2. See how an existing theme is done via ~/.local/share/omarchy/themes/catppuccin.
3. Download a matching background (or several) from the internet and put them in ~/.config/omarchy/themes/[name-of-new-theme] 3. Download a matching background (or several) from the internet and put them in ~/.config/omarchy/themes/[name-of-new-theme]
4. When done with the theme, run omarchy-theme-set "Name of new theme" 4. When done with the theme, run `omarchy theme set "Name of new theme"`
### Pattern 3: Use Hooks for Automation ### Pattern 3: Use Hooks for Automation
@@ -207,7 +216,7 @@ Create scripts in `~/.config/omarchy/hooks/` to run automatically on events:
~/.config/omarchy/hooks/ ~/.config/omarchy/hooks/
├── theme-set # Runs after theme change (receives theme name as $1) ├── theme-set # Runs after theme change (receives theme name as $1)
├── font-set # Runs after font change ├── font-set # Runs after font change
└── post-update # Runs after omarchy-update └── post-update # Runs after `omarchy update`
``` ```
Example hook (`~/.config/omarchy/hooks/theme-set`): Example hook (`~/.config/omarchy/hooks/theme-set`):
@@ -224,8 +233,8 @@ When customizations go wrong:
```bash ```bash
# Reset specific config (creates backup automatically) # Reset specific config (creates backup automatically)
omarchy-refresh-waybar omarchy refresh waybar
omarchy-refresh-hyprland omarchy refresh hyprland
# The refresh command: # The refresh command:
# 1. Backs up current config with timestamp # 1. Backs up current config with timestamp
@@ -238,12 +247,11 @@ omarchy-refresh-hyprland
### Themes ### Themes
```bash ```bash
omarchy-theme-list # Show available themes omarchy theme list # Show available themes
omarchy-theme-current # Show current theme omarchy theme current # Show current theme
omarchy-theme-set <name> # Apply theme (use "Tokyo Night" not "tokyo-night") omarchy theme set <name> # Apply theme (use "Tokyo Night" not "tokyo-night")
omarchy-theme-next # Cycle to next theme omarchy theme bg next # Cycle wallpaper
omarchy-theme-bg-next # Cycle wallpaper omarchy theme install <url> # Install from git repo
omarchy-theme-install <url> # Install from git repo
``` ```
### Keybindings ### Keybindings
@@ -255,11 +263,11 @@ bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exit bind = SUPER SHIFT, E, exit
``` ```
View current bindings: `omarchy-menu-keybindings --print` View current bindings: `omarchy menu keybindings --print`
**IMPORTANT: When re-binding an existing key:** **IMPORTANT: When re-binding an existing key:**
1. First check existing bindings: `omarchy-menu-keybindings --print` 1. First check existing bindings: `omarchy menu keybindings --print`
2. If the key is already bound, you MUST add an `unbind` directive BEFORE your new `bind` 2. If the key is already bound, you MUST add an `unbind` directive BEFORE your new `bind`
3. Inform the user what the key was previously bound to 3. Inform the user what the key was previously bound to
@@ -297,43 +305,43 @@ Window rules go in `~/.config/hypr/hyprland.conf` or a sourced file. Always veri
### Fonts ### Fonts
```bash ```bash
omarchy-font-list # Available fonts omarchy font list # Available fonts
omarchy-font-current # Current font omarchy font current # Current font
omarchy-font-set <name> # Change font omarchy font set <name> # Change font
``` ```
### System ### System
```bash ```bash
omarchy-update # Full system update omarchy update # Full system update
omarchy-version # Show Omarchy version omarchy version # Show Omarchy version
omarchy-debug --no-sudo --print # Debug info (ALWAYS use these flags) omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)
omarchy-system-lock # Lock screen omarchy system lock # Lock screen
omarchy-system-shutdown # Shutdown omarchy system shutdown # Shutdown
omarchy-system-reboot # Reboot omarchy system reboot # Reboot
``` ```
**IMPORTANT:** Always run `omarchy-debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal. **IMPORTANT:** Always run `omarchy debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal.
## Troubleshooting ## Troubleshooting
```bash ```bash
# Get debug information (ALWAYS use these flags to avoid interactive prompts) # Get debug information (ALWAYS use these flags to avoid interactive prompts)
omarchy-debug --no-sudo --print omarchy debug --no-sudo --print
# Upload logs for support # Upload logs for support
omarchy-upload-log omarchy upload log
# Reset specific config to defaults # Reset specific config to defaults
omarchy-refresh-<app> omarchy refresh <app>
# Refresh specific config file # Refresh specific config file
# config-file path is relative to ~/.config/ # config-file path is relative to ~/.config/
# eg. omarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf # eg. `omarchy refresh config hypr/hyprlock.conf` will refresh ~/.config/hypr/hyprlock.conf
omarchy-refresh-config <config-file> omarchy refresh config <config-file>
# Full reinstall of configs (nuclear option) # Full reinstall of configs (nuclear option)
omarchy-reinstall omarchy reinstall
``` ```
## Decision Framework ## Decision Framework
@@ -344,23 +352,23 @@ When user requests system changes:
2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/omarchy/` 2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/omarchy/`
3. **Is it a theme customization?** Create a NEW custom theme directory 3. **Is it a theme customization?** Create a NEW custom theme directory
4. **Is it automation?** Use hooks in `~/.config/omarchy/hooks/` 4. **Is it automation?** Use hooks in `~/.config/omarchy/hooks/`
5. **Is it a package install?** Use `omarchy-pkg-add` (or `omarchy-pkg-aur-add` for AUR-only packages) 5. **Is it a package install?** Use `omarchy install package <pkgs...>` (or `omarchy pkg aur add <pkgs...>` for AUR-only packages)
6. **Unsure if command exists?** Search with `compgen -c | grep omarchy` 6. **Unsure if command exists?** Run `omarchy commands` (or `omarchy <group> --help` for one group)
## Out of Scope ## Out of Scope
This skill intentionally does not cover Omarchy source development. Do not use this skill for: This skill intentionally does not cover Omarchy source development. Do not use this skill for:
- Editing files in `~/.local/share/omarchy/` (`bin/`, `config/`, `default/`, `themes/`, `migrations/`, etc.) - Editing files in `~/.local/share/omarchy/` (`bin/`, `config/`, `default/`, `themes/`, `migrations/`, etc.)
- Creating or editing migrations - Creating or editing migrations
- Running `omarchy-dev-*` commands - Running `omarchy dev ...` commands
## Example Requests ## Example Requests
- "Change my theme to catppuccin" -> `omarchy-theme-set catppuccin` - "Change my theme to catppuccin" -> `omarchy theme set catppuccin`
- "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, add `unbind` if needed, then add `bind` in `~/.config/hypr/bindings.conf` - "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, add `unbind` if needed, then add `bind` in `~/.config/hypr/bindings.conf`
- "Configure my external monitor" -> Edit `~/.config/hypr/monitors.conf` - "Configure my external monitor" -> Edit `~/.config/hypr/monitors.conf`
- "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.conf` - "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.conf`
- "Set up night light to turn on at sunset" -> `omarchy-toggle-nightlight` or edit `~/.config/hypr/hyprsunset.conf` - "Set up night light to turn on at sunset" -> `omarchy toggle nightlight` or edit `~/.config/hypr/hyprsunset.conf`
- "Customize the catppuccin theme colors" -> Create `~/.config/omarchy/themes/catppuccin-custom/` by copying from stock, then edit - "Customize the catppuccin theme colors" -> Create `~/.config/omarchy/themes/catppuccin-custom/` by copying from stock, then edit
- "Run a script every time I change themes" -> Create `~/.config/omarchy/hooks/theme-set` - "Run a script every time I change themes" -> Create `~/.config/omarchy/hooks/theme-set`
- "Reset waybar to defaults" -> `omarchy-refresh-waybar` - "Reset waybar to defaults" -> `omarchy refresh waybar`