From 55434792d16396bfab575a7176ad97ec4f63f6db Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Thu, 13 Aug 2026 17:02:56 +0200 Subject: [PATCH] Cover the shell, capture, browsers, and networking in the manual Add chapters for the top bar and its panels, screenshots and recording, toggles/idle/screensaver, browsers, shell plugins, and networking, which collects the Wi-Fi, DNS, firewall, and Tailscale material that was spread across the FAQ, TUIs, and services chapters. Fill smaller gaps in the existing chapters: user hooks, autostart, menu extensions, printing, power profiles, factory reset, drive and user passwords, passwordless sudo, firmware updates, display text size, and the LocalSend share menu. Co-Authored-By: Claude Fable 5 --- manual/02-getting-started.md | 10 +- manual/03-navigation.md | 2 + manual/04-the-top-bar.md | 142 ++++++++++++++++++ manual/{04-themes.md => 05-themes.md} | 2 +- manual/{05-hotkeys.md => 06-hotkeys.md} | 8 +- ...ory.md => 07-unified-clipboard-history.md} | 0 manual/{07-reminders.md => 08-reminders.md} | 0 manual/{08-notices.md => 09-notices.md} | 2 + ...ion.md => 10-text-extraction-dictation.md} | 0 manual/11-screenshots-recording.md | 78 ++++++++++ manual/12-toggles-idle-screensaver.md | 100 ++++++++++++ .../{10-omarchy-cli.md => 13-omarchy-cli.md} | 6 + manual/{11-terminal.md => 14-terminal.md} | 2 +- manual/{12-neovim.md => 15-neovim.md} | 0 manual/{13-ai.md => 16-ai.md} | 0 ...pment-tools.md => 17-development-tools.md} | 0 .../{15-shell-tools.md => 18-shell-tools.md} | 16 ++ ...ell-functions.md => 19-shell-functions.md} | 0 manual/{17-tuis.md => 20-tuis.md} | 6 +- manual/{18-guis.md => 21-guis.md} | 23 ++- manual/22-browsers.md | 39 +++++ ...ices.md => 23-commercial-apps-services.md} | 12 +- manual/{20-web-apps.md => 24-web-apps.md} | 0 manual/{21-gaming.md => 25-gaming.md} | 0 ...ing-out-pdfs.md => 26-filling-out-pdfs.md} | 0 manual/{23-windows-vm.md => 27-windows-vm.md} | 0 ...other-packages.md => 28-other-packages.md} | 0 manual/{25-updates.md => 29-updates.md} | 4 + manual/{26-dotfiles.md => 30-dotfiles.md} | 36 +++++ manual/31-shell-plugins.md | 102 +++++++++++++ manual/{27-monitors.md => 32-monitors.md} | 10 ++ ...ckpad.md => 33-keyboard-mouse-trackpad.md} | 0 manual/34-branding.md | 27 ---- manual/34-networking.md | 45 ++++++ ...{29-system-sleep.md => 35-system-sleep.md} | 6 + ...ation.md => 36-hardware-authentication.md} | 0 manual/{31-fonts.md => 37-fonts.md} | 0 .../{32-backgrounds.md => 38-backgrounds.md} | 0 manual/{33-prompt.md => 39-prompt.md} | 0 manual/40-branding.md | 43 ++++++ ...5-common-tweaks.md => 41-common-tweaks.md} | 0 ...{36-extra-themes.md => 42-extra-themes.md} | 0 ...n-theme.md => 43-making-your-own-theme.md} | 8 +- .../{38-mac-support.md => 44-mac-support.md} | 0 ...oubleshooting.md => 45-troubleshooting.md} | 10 +- manual/{40-faq.md => 46-faq.md} | 24 ++- ...em-snapshots.md => 47-system-snapshots.md} | 6 + manual/{42-security.md => 48-security.md} | 10 ++ manual/{43-omarchy-on.md => 49-omarchy-on.md} | 0 ...oot-install.md => 50-dual-boot-install.md} | 0 ...-installs.md => 51-unattended-installs.md} | 0 51 files changed, 736 insertions(+), 43 deletions(-) create mode 100644 manual/04-the-top-bar.md rename manual/{04-themes.md => 05-themes.md} (96%) rename manual/{05-hotkeys.md => 06-hotkeys.md} (96%) rename manual/{06-unified-clipboard-history.md => 07-unified-clipboard-history.md} (100%) rename manual/{07-reminders.md => 08-reminders.md} (100%) rename manual/{08-notices.md => 09-notices.md} (55%) rename manual/{09-text-extraction-dictation.md => 10-text-extraction-dictation.md} (100%) create mode 100644 manual/11-screenshots-recording.md create mode 100644 manual/12-toggles-idle-screensaver.md rename manual/{10-omarchy-cli.md => 13-omarchy-cli.md} (85%) rename manual/{11-terminal.md => 14-terminal.md} (98%) rename manual/{12-neovim.md => 15-neovim.md} (100%) rename manual/{13-ai.md => 16-ai.md} (100%) rename manual/{14-development-tools.md => 17-development-tools.md} (100%) rename manual/{15-shell-tools.md => 18-shell-tools.md} (73%) rename manual/{16-shell-functions.md => 19-shell-functions.md} (100%) rename manual/{17-tuis.md => 20-tuis.md} (87%) rename manual/{18-guis.md => 21-guis.md} (68%) create mode 100644 manual/22-browsers.md rename manual/{19-commercial-apps-services.md => 23-commercial-apps-services.md} (69%) rename manual/{20-web-apps.md => 24-web-apps.md} (100%) rename manual/{21-gaming.md => 25-gaming.md} (100%) rename manual/{22-filling-out-pdfs.md => 26-filling-out-pdfs.md} (100%) rename manual/{23-windows-vm.md => 27-windows-vm.md} (100%) rename manual/{24-other-packages.md => 28-other-packages.md} (100%) rename manual/{25-updates.md => 29-updates.md} (89%) rename manual/{26-dotfiles.md => 30-dotfiles.md} (66%) create mode 100644 manual/31-shell-plugins.md rename manual/{27-monitors.md => 32-monitors.md} (87%) rename manual/{28-keyboard-mouse-trackpad.md => 33-keyboard-mouse-trackpad.md} (100%) delete mode 100644 manual/34-branding.md create mode 100644 manual/34-networking.md rename manual/{29-system-sleep.md => 35-system-sleep.md} (61%) rename manual/{30-hardware-authentication.md => 36-hardware-authentication.md} (100%) rename manual/{31-fonts.md => 37-fonts.md} (100%) rename manual/{32-backgrounds.md => 38-backgrounds.md} (100%) rename manual/{33-prompt.md => 39-prompt.md} (100%) create mode 100644 manual/40-branding.md rename manual/{35-common-tweaks.md => 41-common-tweaks.md} (100%) rename manual/{36-extra-themes.md => 42-extra-themes.md} (100%) rename manual/{37-making-your-own-theme.md => 43-making-your-own-theme.md} (70%) rename manual/{38-mac-support.md => 44-mac-support.md} (100%) rename manual/{39-troubleshooting.md => 45-troubleshooting.md} (75%) rename manual/{40-faq.md => 46-faq.md} (64%) rename manual/{41-system-snapshots.md => 47-system-snapshots.md} (70%) rename manual/{42-security.md => 48-security.md} (71%) rename manual/{43-omarchy-on.md => 49-omarchy-on.md} (100%) rename manual/{44-dual-boot-install.md => 50-dual-boot-install.md} (100%) rename manual/{45-unattended-installs.md => 51-unattended-installs.md} (100%) diff --git a/manual/02-getting-started.md b/manual/02-getting-started.md index 0cbd8a40..009c0de4 100644 --- a/manual/02-getting-started.md +++ b/manual/02-getting-started.md @@ -1,6 +1,6 @@ # Getting Started -Omarchy is installed using an ISO. You can choose between a full-disk install, which takes over the entire drive, or a free-space install, which puts Omarchy in the unallocated space on a drive — that's how you dual boot alongside Windows or another OS (see [dual-boot install](44-dual-boot-install.md) — note that you'll need to turn off BitLocker in Windows first). Either way, the installation uses full-disk encryption, and the full-disk option will wipe the selected drive, so be sure to take a backup before using an existing one! +Omarchy is installed using an ISO. You can choose between a full-disk install, which takes over the entire drive, or a free-space install, which puts Omarchy in the unallocated space on a drive — that's how you dual boot alongside Windows or another OS (see [dual-boot install](50-dual-boot-install.md) — note that you'll need to turn off BitLocker in Windows first). Either way, the installation uses full-disk encryption, and the full-disk option will wipe the selected drive, so be sure to take a backup before using an existing one! [Download the Omarchy ISO](https://omarchy.org/) first, put it on a USB stick (use [balenaEtcher](https://etcher.balena.io/) on Mac/Windows or [caligula](https://github.com/ifd3f/caligula) on Linux), and boot off the stick. @@ -24,9 +24,15 @@ The full-disk encryption won't allow you to enter the password from a Bluetooth If you're setting up a machine for someone else — a family member, a new employee, a buyer — you shouldn't be answering the personal questions on their behalf. Hit `Ctrl + C` on the very first screen of the installer (the keyboard selection), and Omarchy will offer to prepare the machine for another owner instead. The system installs right away, but all the personal setup — keyboard layout, username, password — is deferred until the machine boots for the first time. The drive is still encrypted by default, and the password the new owner picks on that first boot becomes the encryption password too. +### Passing on a machine you've already used + +If the machine is one you've been using yourself, you don't have to reinstall it to hand it over. Run _Setup > Reset Computer_ in the Omarchy menu, type `reset` to confirm, and reboot. That wipes every user account and everything in `/home`, throws away all the packages and system changes you made since installation, and clears the machine's identity — network connections, host keys, and all. What comes back up is the setup wizard from the first boot, ready for its new owner to enter their own name, password, and encryption password. + +It works by restoring the baseline snapshot the installer takes, so it's only available on machines installed from the Omarchy ISO. And on a drive without encryption, a reset is deletion rather than a secure erase, so if the data was sensitive, do a fresh install instead. + ### Unattended installs -The ISO can also install completely on its own — no keyboard, no wizard — when it's handed its configuration on a second drive. That's the way to treat Omarchy as a base image for VMs and fleet machines. See [unattended installs](45-unattended-installs.md). +The ISO can also install completely on its own — no keyboard, no wizard — when it's handed its configuration on a second drive. That's the way to treat Omarchy as a base image for VMs and fleet machines. See [unattended installs](51-unattended-installs.md). ### No-encryption installations diff --git a/manual/03-navigation.md b/manual/03-navigation.md index 5d9b66fb..20663431 100644 --- a/manual/03-navigation.md +++ b/manual/03-navigation.md @@ -36,6 +36,8 @@ But you can also choose to turn a workspace into the scrolling layout where wind ![niri-layout.png](https://learn.omacom.io/u/niri-layout-LvV25i.png) +The choice is per workspace, and it sticks. So you can keep workspace 1 on dwindle for browsing and workspace 2 on scrolling for code, and they'll come back that way after a restart. (The same toggle is under _Trigger > Toggle > Workspace Layout_ in the Omarchy menu). + If you wish to use the scrolling layout as the default, you can set that in `~/.config/hypr/looknfeel.lua`: ```lua diff --git a/manual/04-the-top-bar.md b/manual/04-the-top-bar.md new file mode 100644 index 00000000..9385dbc8 --- /dev/null +++ b/manual/04-the-top-bar.md @@ -0,0 +1,142 @@ +# The Top Bar + +The strip along the top of your screen is the Omarchy bar. It's not a bolted-on status bar but part of the Omarchy shell, the single long-running Quickshell process that also draws the menu, the notifications, the OSD popups, and the lock screen. That's why it themes perfectly with everything else and why a panel opens instantly instead of spawning a new app. + +It's also the one piece of the desktop that's always on screen, so it's worth knowing what all those little glyphs do. + +## What's on it by default + +The bar has three sections. On the left sits the Omarchy logo (the menu launcher) and the workspace indicators. In the center you get the status indicators, the clock, the keyboard layout, the weather, and an Omarchy update badge. On the right: the system tray, agents, bluetooth, network, audio, display, and power. + +A few of those only show up when they have something to say. The keyboard layout appears only if you've configured more than one layout. The update badge appears only when there's an Omarchy update waiting. And the agents icon appears the first time Omarchy finds AI coding usage on the machine (see [AI](16-ai.md)). + +## Clicking around + +Nearly every widget does something on left, right, and middle click, and several respond to scrolling. This is the part people miss — the right and middle buttons are where a lot of the good stuff hides. + +| Widget | Left | Right | Middle / scroll | +| --- | --- | --- | --- | +| Menu | Omarchy menu | New terminal | — | +| Workspaces | Focus that workspace | — | — | +| Clock | Calendar popup | Cycle the label format | Middle: timezone picker | +| Weather | Forecast popup | Full weather as a notification | Middle: refresh | +| Audio | Audio panel | Mute | Middle: panel · scroll: volume | +| Microphone | Mute the mic | — | Middle: audio panel · scroll: input volume | +| Network | Network panel | `nmtui` in a terminal | — | +| Bluetooth | Bluetooth panel | Toggle the radio | Middle: `bluetoothctl` TUI | +| Display | Display panel | — | — | +| Power | Power panel | Toggle the battery percentage | — | +| Media | Play/pause | Cover-art popup | Middle: next · scroll: prev/next | +| Agents | Agents panel | Launch your agent | Middle: next subscription | +| Tray | Hover to reveal the drawer | Right on the chevron to manage | — | +| Omarchy update | Run the update | — | — | + +Not everything in that table is on your bar out of the box. The media widget (MPRIS now-playing, with a scrolling track and artist) and the microphone widget are both built in but off by default — add them if you want them, as described below. + +## The panels + +Clicking a bar icon opens a panel, which is a proper popup with sliders, lists, and keyboard navigation rather than a tooltip. Each one also has a hotkey, so you never have to aim at a 16-pixel glyph: + +| Hotkey | Panel | +| --- | --- | +| `Super + Ctrl + A` | Audio | +| `Super + Ctrl + W` | Network | +| `Super + Ctrl + B` | Bluetooth | +| `Super + Ctrl + D` | Display | +| `Super + Ctrl + P` | Power | +| `Super + Ctrl + Alt + D` | Calendar | +| `Super + Ctrl + 1-9` | Toggle the nth panel in the right section | + +The panels aren't read-outs. They're where you actually do the thing: + +- **Audio** has a master volume slider, an output-device picker, and a per-app mixer, so you can turn down that one browser tab without touching everything else. +- **Network** scans for Wi-Fi, shows signal strength, connects, and lets you pick a DNS provider. +- **Bluetooth** lists your devices with connect/disconnect and battery levels. +- **Power** shows battery stats, switches power profiles (it remembers a separate choice for battery and AC), and prints some system info. +- **Display** carries a brightness slider, text size, monitor scaling presets, and — when you have more than one screen — per-monitor controls. See [monitors](32-monitors.md) for the deeper story. +- **Clock** opens a month grid with ISO week numbers and month stepping. + +Every panel takes the keyboard as well as the mouse: arrows move, Return activates, Tab steps to the neighbouring panel, and Escape closes. + +`Super + Ctrl + 1-9` counts panels left to right in the right section, skipping the tray since it has no panel of its own. So the number matches the icon you'd point at. + +### Panels without a bar icon + +A few panels live in the shell but never take up bar space. They're summoned from the [menu](03-navigation.md) instead: + +- **Trigger → Speed Test → Network Speed Test** runs an internet speed test with download and upload dials. +- **Trigger → Speed Test → Disk Speed Test** does the same for disk read and write. +- **Setup → Network → QR Code** turns your current Wi-Fi network into a QR code someone can scan to join. Lovely for guests. + +### Tailscale and Dropbox + +Two more widgets appear on the bar only once you install the matching service from **Install → Service**, and both are worth knowing about because they do more than report status. + +The **Tailscale** panel connects and disconnects the tailnet, switches between accounts, and picks an exit node (your own machines and Mullvad regions both show up in that list). It also browses your machines — and with one selected, `s` sends files to it over Taildrop, which is the fastest way to move a file to your phone or another laptop. `c` copies the machine's IP, `n` its name, and `d` its full DNS name. There's a send button on each machine row too, if you'd rather click. The same thing from the terminal is `omarchy tailscale send [file...]`. + +The **Dropbox** panel handles login, shows how much storage you've used, and lists recently synced files. + +Removing either service takes its widget back off the bar. + +## Indicators + +The little cluster in the center is the indicators widget. These are status glyphs for modes you've turned on: do not disturb, night light, a queued [reminder](08-reminders.md), an active screen recording, stay awake, and [dictation](10-text-extraction-dictation.md). They light up when the mode is active and otherwise stay out of the way — hover the center of the bar to peek at the inactive ones. Clicking an indicator toggles that mode. + +If you'd rather they were always visible, set `alwaysShow` to `true` on the widget. And if you only care about some of them, list the ones you want in `items`: `["Dnd", "Reminder", "NightLight"]`. You can have more than one indicators widget, so different sections can show different subsets. + +## Rearranging the bar + +The bar configures itself. You don't have to open a config file to move things. + +Grab an empty patch of the bar around the center and drag it toward another screen edge, and the bar moves there — left, right, top, or bottom all work, and every widget adapts (vertical bars fall back to compact icon-only forms). A click-and-hold starts the same drag. Double-left-click that same empty space to toggle transparency. And drag any widget to reorder it or throw it into another section. + +The same things have commands, which is what you want for a [dotfiles](30-dotfiles.md) setup: + +```bash +omarchy bar position bottom +omarchy bar transparent toggle +omarchy bar move omarchy.clock --section center --index 0 +omarchy bar set omarchy.clock format "HH:mm" +omarchy bar defaults # back to the shipped layout +``` + +To add or remove a widget entirely, use the plugin commands. `omarchy plugin list` prints every widget the shell knows about with its id, and then: + +```bash +omarchy plugin enable omarchy.media --section center +omarchy plugin disable omarchy.weather +``` + +There's also a menu route for the common bits: **Style → Menu Bar** has position and transparency. + +## Hiding the bar + +`Super + Shift + Space` toggles the bar off and back on without killing the shell — panels and hotkeys keep working, you just get the pixels back. It's also in the menu under **Trigger → Toggle → Menu Bar**. + +## The config file + +All of it is stored in `~/.config/omarchy/shell.json`, under the `bar` key. Here's a trimmed version: + +```json +{ + "version": 1, + "bar": { + "position": "top", + "transparent": false, + "centerAnchor": "omarchy.clock", + "layout": { + "left": [{ "id": "omarchy.menu" }, { "id": "omarchy.workspaces" }], + "center": [{ "id": "omarchy.clock", "format": "HH:mm" }], + "right": [{ "id": "omarchy.audio" }, { "id": "omarchy.power" }] + } + } +} +``` + +Every widget is one entry in one of the three layout arrays, and its settings sit inline on that entry — there's no separate settings file and no `config` sub-object. The clock's `format`, `formatAlt` (what right-click cycles to), and `verticalFormat` all live right there on `{ "id": "omarchy.clock" }`. + +`centerAnchor` names the one center widget that gets pinned to the exact center of the screen, with the others flanking it. That's how the clock stays dead center even as the weather and update badge come and go. Set it to an empty string and the center list is just centered as a group instead. + +One rule worth internalizing: **once you have your own `shell.json`, it's canonical**. Until you customize anything, the shell reads Omarchy's default file. The moment you drag a widget, run `omarchy bar`, or edit the file yourself, you own it — there's no deep merge, so new default widgets in future Omarchy releases won't appear on your bar automatically. `omarchy bar defaults` puts the shipped layout back whenever you want a clean slate. + +The same file also holds your idle timings at the top level, outside the `bar` key: `idle.screensaver` and `idle.lock`, both in seconds since you went idle. So the default screensaver kicks in at 150 seconds and the lock at 300. diff --git a/manual/04-themes.md b/manual/05-themes.md similarity index 96% rename from manual/04-themes.md rename to manual/05-themes.md index a7e32f56..f56de999 100644 --- a/manual/04-themes.md +++ b/manual/05-themes.md @@ -6,7 +6,7 @@ Each theme styles the desktop, terminal, neovim, activity screen (btop), Chromiu Themes have a set of background images that you can pick between using `Super + Ctrl + Space`. -You can find even more themes on [the extra themes page](36-extra-themes.md) or even [make your own theme](37-making-your-own-theme.md). +You can find even more themes on [the extra themes page](42-extra-themes.md) or even [make your own theme](43-making-your-own-theme.md). ![tokyo-night.png](https://learn.omacom.io/u/tokyo-night-yN9jzd.png) _Tokyo Night_ diff --git a/manual/05-hotkeys.md b/manual/06-hotkeys.md similarity index 96% rename from manual/05-hotkeys.md rename to manual/06-hotkeys.md index 3f0d2876..845a1382 100644 --- a/manual/05-hotkeys.md +++ b/manual/06-hotkeys.md @@ -75,6 +75,7 @@ You can see all the main keyboard bindings with `Super + K` (Tmux bindings with | `Super + Ctrl + O` | Toggle menu | | `Super + Ctrl + H` | Hardware menu | | `Super + Ctrl + Q` | Calculator | +| `Super + Ctrl + E` | Emoji picker | | `Super + Ctrl + .` | Transcode media | | `Super + Shift + Ctrl + A` | Pick an AI agent | @@ -86,6 +87,10 @@ You can see all the main keyboard bindings with `Super + K` (Tmux bindings with | `Shift + Brightness Down` | Minimum screen brightness | | `Alt + Brightness Up/Down` | Precise 1% brightness changes | | `Alt + Volume Up/Down` | Precise 1% volume changes | +| `Keyboard Brightness Up/Down` | Keyboard backlight brighter/dimmer | +| `Keyboard Backlight` | Cycle the keyboard backlight levels | +| `Alt + Play` | Next track | +| `Alt + Shift + Play` | Previous track | ## Launching apps @@ -144,10 +149,11 @@ Usually on Linux, you need `Ctrl + Shift + C/V` to copy'n'paste in the terminal | `Super + Alt + [` | Make webcam overlay smaller while recording | | `Super + Alt + ]` | Make webcam overlay larger while recording | | `Alt + Shift + L` | Copy current URL from webapp or Chromium | +| `Alt + Shift + D` | Download the video on the current page to `~/Videos` | | `Super + Ctrl + X` | Start/stop dictation (requires _Install > AI > Dictation_) | | `F9` | Push-to-talk dictation (requires _Install > AI > Dictation_) | -With screenrecordings, hit the hotkey to start, hit it again to stop. +With screenrecordings, the hotkey first asks which audio you want, then starts recording. Hit it again to stop. See [screenshots and recording](11-screenshots-recording.md) for the details. All capture options are also accessible under _Trigger > Capture_ in the Omarchy menu (`Super + Space`). diff --git a/manual/06-unified-clipboard-history.md b/manual/07-unified-clipboard-history.md similarity index 100% rename from manual/06-unified-clipboard-history.md rename to manual/07-unified-clipboard-history.md diff --git a/manual/07-reminders.md b/manual/08-reminders.md similarity index 100% rename from manual/07-reminders.md rename to manual/08-reminders.md diff --git a/manual/08-notices.md b/manual/09-notices.md similarity index 55% rename from manual/08-notices.md rename to manual/09-notices.md index 8c964565..480e7aed 100644 --- a/manual/08-notices.md +++ b/manual/09-notices.md @@ -14,6 +14,8 @@ You can quickly access the date and time, battery status, and current weather us ![weather-notice.png](https://learn.omacom.io/u/weather-notice-MV7Jj1.png) +The location is detected from your IP address, which is usually close enough, but not always. You can pin it down with `omarchy weather location --set Malibu`, or be exact about it by adding coordinates: `omarchy weather location --set Malibu 34.0259,-118.7798`. Run `omarchy weather location` on its own to see where it thinks you are, and `--clear` to go back to auto-detection. + ### Battery `Super + Ctrl + Alt + B` diff --git a/manual/09-text-extraction-dictation.md b/manual/10-text-extraction-dictation.md similarity index 100% rename from manual/09-text-extraction-dictation.md rename to manual/10-text-extraction-dictation.md diff --git a/manual/11-screenshots-recording.md b/manual/11-screenshots-recording.md new file mode 100644 index 00000000..58f12485 --- /dev/null +++ b/manual/11-screenshots-recording.md @@ -0,0 +1,78 @@ +# Screenshots & Recording + +Everything you can grab off the screen hangs off the Print Screen key. One key on its own takes a picture, and the modifiers take a recording, a colour, or the text inside a region. If your keyboard doesn't have a Print Screen key at all, `Super + Ctrl + C` opens the same set as a menu. + +| Hotkey | Function | +| ------ | -------- | +| `Print Screen` | Screenshot | +| `Alt + Print Screen` | Screenrecord (or stop the one that's running) | +| `Super + Print Screen` | Colour picker | +| `Super + Ctrl + Print Screen` | Extract text from a region | +| `Super + Ctrl + C` | Capture menu | +| `Super + Ctrl + .` | Transcode a picture or video | + +## Screenshots + +Hit `Print Screen` and the screen freezes so nothing shifts under you while you aim. Drag a box for a freeform region, or just click once and the shot snaps to whatever rectangle you clicked in — a window if you landed on one, the whole monitor if you landed on the bar or in a gap. Changed your mind? Hit `Print Screen` again to dismiss the picker. + +The result goes two places at once: a PNG in your pictures directory, and the clipboard, so you can paste it straight into a chat window with `Super + V`. A notification pops up with a thumbnail. Click it (or hit `Super + Alt + ,` to invoke the last notification) and the shot opens in Tensaku, the annotation editor, where you can draw arrows and boxes on it before you send it. + +Files land in `~/Pictures` by default, named `screenshot-2026-08-13_14-22-05.png`. If you'd rather keep them in their own folder, set `OMARCHY_SCREENSHOT_DIR` — see [the FAQ](46-faq.md) for where to put session environment variables. Omarchy creates the directory for you if it isn't there. You can swap the editor too with `OMARCHY_SCREENSHOT_EDITOR`. + +From the terminal, `omarchy screenshot` takes the same shot, and you can be explicit about it: `omarchy capture screenshot region` for freeform only, `windows` to snap to window and monitor rectangles, or `fullscreen` to skip the picker entirely and grab the focused monitor. A second argument of `copy` puts the shot only on the clipboard, and `save` only on disk. + +### Driving the picker from the keyboard + +While the selection is up, you don't have to use the mouse at all: + +| Key | Function | +| --- | -------- | +| `Return` | Capture the highlighted window | +| `Ctrl + Return` | Capture the whole screen | +| `Tab` / `Ctrl + Tab` | Highlight the next / previous window | +| Arrow keys | Highlight the window in that direction | + +The arrows and Tab move the cursor to the window they pick, so the highlight follows along and you can see what you're about to capture. These bindings only exist while a selection is on screen, so they can't collide with anything in your own config. + +## Screen recording + +`Alt + Print Screen` opens _Trigger > Capture > Screenrecord_, which asks what you want on the soundtrack: no audio, desktop audio, desktop plus microphone, or desktop plus microphone plus webcam. That last one only shows up if you actually have a camera plugged in. Pick one and you get the same picker as a screenshot: drag a region, or click a window or monitor. + +Recording runs on gpu-screen-recorder, which encodes on the GPU at 60fps and falls back to the CPU if it has to. The result is an MP4 in `~/Videos`, named `screenrecording-2026-08-13_14-22-05.mp4`. Set `OMARCHY_SCREENRECORD_DIR` to change that — but note that unlike the screenshot directory, this one has to exist already, or the recording refuses to start. + +While you're recording, a little indicator shows up in the bar. Click it to stop. You can also stop with `Alt + Print Screen` again, or with the _Stop Screenrecording_ entry under _Trigger > Capture > Screenrecord_, which only appears while something is actually recording. + +Stopping does a bit of tidying before it hands you the file: the first frame gets trimmed, and if there's audio it's normalized to -14 LUFS with the PipeWire capture pop at the very start muted out. Then a notification appears with a thumbnail from the recording. Click it to play the file in mpv. + +### The webcam overlay + +When you record with a webcam, the camera appears as a pinned, cropped portrait window in the bottom-right corner of whatever you're recording. If it's sitting on top of something you need, resize it on the fly: + +| Hotkey | Function | +| ------ | -------- | +| `Super + Alt + [` | Make the webcam overlay smaller | +| `Super + Alt + ]` | Make the webcam overlay larger | + +There are three sizes — small, medium, and large — and the hotkeys step between them. Medium is the default. They're proportional to the recording, so the camera takes up the same share of the frame whether you're recording a 1080p monitor or a 6K one. And if you recorded a region rather than a whole display, the overlay anchors to that region's corner rather than the monitor's, so it stays inside the shot. + +You can also call it directly with `omarchy-capture-webcam-resize small`, or `reset` to go back to medium. + +## Text, QR codes, and colours + +`Super + Ctrl + Print Screen` selects a region and OCRs it to the clipboard. That's covered properly in [Text Extraction & Dictation](10-text-extraction-dictation.md). + +_Trigger > Capture > QR Code_ does the same trick for QR codes. Select the region with the code in it, and the decoded value goes to the clipboard. It only looks for QR codes — dense screen content has a habit of false-positiving as a barcode otherwise. Worth knowing: the decoded value goes to the clipboard and nowhere else. It isn't printed, it isn't in the notification, and it's marked sensitive so it doesn't stick around in [clipboard history](07-unified-clipboard-history.md). QR codes routinely carry secrets — the `otpauth://` URI behind a 2FA setup code, for one — and you don't want that in a log. Pasting still works fine. + +`Super + Print Screen` (or _Trigger > Capture > Color_) turns the cursor into an eyedropper. Click anything on screen and the colour lands on the clipboard. Press the hotkey again to back out without picking. + +## Transcoding before you share + +A 4K screen recording or a raw HEIC off your phone is often too big to just send. `Super + Ctrl + .` (or _Trigger > Transcode_) fixes that. It offers you a fuzzy file picker over `~/Pictures` and `~/Videos`, then asks for a format and a size. + +Pictures go to jpg or png at high, medium, or low, which cap the width at 3160, 2160, and 1080 pixels. Videos go to mp4 or an animated gif at 4k, 1080p, or 720p. The converted file is written next to the original with the resolution in the name — `demo-1080p.mp4` — and the path is copied to the clipboard as a file URI, so you can paste it directly into an app that takes file drops. + +It works from the terminal too, if you already know what you want: `omarchy transcode ~/Videos/demo.mov mp4 1080p`. There's also `omarchy transcode ascii`, which turns an image into ASCII art — that one's mostly for [branding](40-branding.md). + +## Sending it somewhere + +Once you've got the file, `Super + Ctrl + S` opens the Share menu and sends it to another device on your network via LocalSend. See [GUIs](21-guis.md) for that. diff --git a/manual/12-toggles-idle-screensaver.md b/manual/12-toggles-idle-screensaver.md new file mode 100644 index 00000000..862e54d2 --- /dev/null +++ b/manual/12-toggles-idle-screensaver.md @@ -0,0 +1,100 @@ +# Toggles, Idle & the Screensaver + +A lot of what you change day to day isn't really a setting. It's a mode you flip on for an hour and off again: night light while you're working late, do not disturb while you're presenting, stay awake while you're watching something. Omarchy calls those toggles, and they all work the same way — a hotkey, a menu entry, and a command, all hitting the same switch. + +### The toggle menu + +`Super + Ctrl + O` opens _Trigger > Toggle_ directly, or you can walk there from the Omarchy menu (`Super + Space`). Everything in that list is a switch you can flip without thinking about where the state lives. + +From the terminal, the same switches are `omarchy toggle `. Run `omarchy toggle` on its own to see the whole group. + +| Toggle | Hotkey | Command | +| ------ | ------ | ------- | +| Night light | `Super + Ctrl + N` | `omarchy toggle nightlight` | +| Silence notifications | `Super + Ctrl + ,` | `omarchy toggle notification silencing` | +| Stay awake (no idle lock) | `Super + Ctrl + I` | `omarchy toggle idle` | +| Screensaver | — | `omarchy toggle screensaver` | +| Menu bar | `Super + Shift + Space` | `omarchy toggle bar` | +| Touchpad | `XF86TouchpadToggle` | `omarchy toggle touchpad` | +| Touchscreen | — | `omarchy toggle touchscreen` | +| Suspend | — | `omarchy toggle suspend` | +| Hybrid GPU | — | `omarchy toggle hybrid gpu` | + +The touchpad, touchscreen, and hybrid GPU switches live under _Trigger > Hardware_ (`Super + Ctrl + H`) rather than under Toggle, since they only show up when you actually have that hardware. The touchpad and touchscreen ones survive a Hyprland reload — the disabled state is written back out as a small Lua file that Hyprland sources on startup. + +The Toggle menu also carries a few things that aren't `omarchy toggle` commands but behave the same: battery percentage in the bar, workspace layout (`Super + L`), window gaps (`Super + Shift + Backspace`), and the 1-window square aspect (`Super + Ctrl + Backspace`). + +Most of these are just a flag file under `~/.local/state/omarchy/toggles/`. If you want to branch on one in a script, `omarchy-toggle-enabled` gives you an exit code instead of making you go looking: + +```bash +omarchy-toggle-enabled screensaver-off && echo "screensaver is off" +``` + +The flags are named for the off state — `screensaver-off`, `suspend-off`, `bar-off` — so their presence means the feature is disabled. + +### Indicators in the bar + +When a mode is on, you get a small glyph in the middle of the top bar next to the clock. That's the indicators widget, and it carries dictation, screen recording, pending reminders, night light, do not disturb, and stay awake. + +Inactive indicators are hidden. Hover the area around them and they fade in dimmed, so you can click one to turn it on without knowing its hotkey. Clicking an active one turns it back off. If you'd rather see all of them all the time, set `alwaysShow` to `true` on the `omarchy.indicators` entry in `~/.config/omarchy/shell.json` — see [the top bar](04-the-top-bar.md) for how bar widgets are configured. + +### Night light + +`Super + Ctrl + N` warms the screen to 4000K, and hitting it again puts it back to 6500K. It's driven by hyprsunset, which the toggle starts for you if it isn't already running. + +By default hyprsunset does nothing to your screen at all. `~/.config/hypr/hyprsunset.conf` ships with an identity profile precisely so the display stays untouched until you ask for warmth. If you'd rather have it switch by the clock, replace that with a time profile: + +``` +profile { + time = 20:00 + temperature = 4000 +} +``` + +Then start hyprsunset at login by adding `o.launch_on_start("hyprsunset")` to `~/.config/hypr/autostart.lua`. The 4000K/6500K pair used by the toggle is fixed, so the config file is where you go if you want a different temperature. + +### Do not disturb + +`Super + Ctrl + ,` silences notifications. No toasts pop up while it's on, and the crossed-out bell indicator sits in the bar to remind you why the desktop has gone quiet. + +Nothing is lost, though. A silenced notification is written straight into your notification history, which is exactly the record you want when you come back and wonder what you missed. Open it with `Super + Shift + Alt + ,`. See [notices](09-notices.md) for the rest of the notification story. + +Two kinds of message still get through: Omarchy's own confirmation toasts for something you just did ("Theme changed", "Screenshot saved"), and critical alerts sent from the command line. Chat apps that mark everything critical to force their way in front of you don't qualify. + +### Idle + +The Omarchy shell owns idle behavior, and the timings are a top-level `idle` block in `~/.config/omarchy/shell.json`: + +```json +{ + "version": 1, + "idle": { + "screensaver": 150, + "lock": 300 + } +} +``` + +Both numbers are seconds counted from the moment you went idle — not from each other. So with the defaults, the screensaver comes up after two and a half minutes and the lock screen takes over at five minutes, whether or not the screensaver ran. Save the file and the shell picks up the new timings right away. + +If you dismiss the screensaver before the lock deadline, that counts as activity and the pending lock is cancelled. You don't get locked out for glancing at your machine. + +To stop locking on idle entirely, `Super + Ctrl + I` — or `omarchy toggle idle` — flips stay awake on, and the coffee cup indicator appears in the bar. That's the one to hit before a long presentation or a build you want to watch. Hit it again to go back to normal. `omarchy toggle idle status` prints the current state as JSON if you need it from a script. + +This is about locking and the screensaver, not power. Suspend and hibernation have their own setup in [system sleep](35-system-sleep.md). + +### The screensaver + +Omarchy's screensaver is ASCII art running through random text effects, one instance per monitor. Any key or mouse movement exits it. + +You can start it on demand from _System > Screensaver_ (`Super + Esc`), which forces it up even if you've turned the idle screensaver off. There's no hotkey bound to it by default. + +`omarchy toggle screensaver` is what turns the idle one off, if you'd rather go straight from working to locked. It needs a terminal it knows how to configure — Alacritty, Foot, Ghostty, or Kitty — and will tell you so if your default terminal is something else. + +The logo it draws is yours to change, under _Style > Screensaver_. Upload a png or svg and Omarchy converts it to ASCII. See [branding](40-branding.md). + +### The lock screen + +`Super + Ctrl + L` locks the machine. That runs the lock screen from the Omarchy shell, blanks the display, resets your keyboard layout to the first one so you're not typing your password in the wrong alphabet, and — if you have it running — locks 1Password on the way out. + +The lock screen takes a password, and it'll take a fingerprint too once you've set one up. That, and the other ways to authenticate, are covered in [hardware authentication](36-hardware-authentication.md). diff --git a/manual/10-omarchy-cli.md b/manual/13-omarchy-cli.md similarity index 85% rename from manual/10-omarchy-cli.md rename to manual/13-omarchy-cli.md index 542ff2c3..fa5d0a05 100644 --- a/manual/10-omarchy-cli.md +++ b/manual/13-omarchy-cli.md @@ -54,3 +54,9 @@ Capture commands — Screenshots and screen recording: omarchy capture text Extract text from a screenshot region with OCR omarchy capture webcam resize Resize the active webcam recording overlay ``` + +Every command takes `--help` too, whether you ask a whole group (`omarchy capture --help`) or a single command (`omarchy capture screenshot --help`). + +### Opening the menu from the terminal + +The Omarchy menu is scriptable as well, which is handy for your own keybindings. `omarchy menu` opens it at the root, and you can jump straight to any point in the tree by naming it: `omarchy menu summon style.theme` goes right to the theme picker, `omarchy menu toggle system` opens the system menu and closes it again if it's already up, and `omarchy menu close` puts it away. diff --git a/manual/11-terminal.md b/manual/14-terminal.md similarity index 98% rename from manual/11-terminal.md rename to manual/14-terminal.md index e8bf283c..fc1c4839 100644 --- a/manual/11-terminal.md +++ b/manual/14-terminal.md @@ -12,7 +12,7 @@ Tmux provides a consistent, programmable interface for panes, windows (aka tabs) You start a new Tmux session in a fresh terminal using `Super + Alt + Return`, and because Tmux is a persistent process, you can resume your session even if you close that terminal. Just hit `Ctrl + Space` (called the prefix key) then `s` to see all your active sessions. -Omarchy ships with an ergonomically-optimized Tmux configuration, which has a lot of keybindings to learn, so keep [the cheatsheet handy](05-hotkeys.md#tmux). +Omarchy ships with an ergonomically-optimized Tmux configuration, which has a lot of keybindings to learn, so keep [the cheatsheet handy](06-hotkeys.md#tmux). ## Tmux layout functions diff --git a/manual/12-neovim.md b/manual/15-neovim.md similarity index 100% rename from manual/12-neovim.md rename to manual/15-neovim.md diff --git a/manual/13-ai.md b/manual/16-ai.md similarity index 100% rename from manual/13-ai.md rename to manual/16-ai.md diff --git a/manual/14-development-tools.md b/manual/17-development-tools.md similarity index 100% rename from manual/14-development-tools.md rename to manual/17-development-tools.md diff --git a/manual/15-shell-tools.md b/manual/18-shell-tools.md similarity index 73% rename from manual/15-shell-tools.md rename to manual/18-shell-tools.md index 8675ab71..69965fdd 100644 --- a/manual/15-shell-tools.md +++ b/manual/18-shell-tools.md @@ -38,6 +38,22 @@ The full manual can be found via `man eza`. The full manual can be found via `man fd`. +## bat + +[bat](https://github.com/sharkdp/bat) is `cat` with syntax highlighting, line numbers, and paging. Run `bat somefile.rb` and you'll see why it's hard to go back. It's also quietly doing work for you elsewhere: it's what colors your man pages, and what renders the previews in `ff`. + +The full manual can be found via `man bat`. + +## tldr + +[tldr](https://tldr.sh/) is the antidote to man pages that open with three screens of history before showing you a single example. `tldr tar` gives you the handful of invocations you actually wanted. + +## yt-dlp + +[yt-dlp](https://github.com/yt-dlp/yt-dlp) downloads video from YouTube and hundreds of other sites. `yt-dlp ` grabs the best quality available into the current directory. + +The full manual can be found via `man yt-dlp`. + ## try [try](https://github.com/tobi/try) makes it easy to manage programming experiments with date-stamped directories. All experiments live in `~/Work/tries` and you can access them via `try`. diff --git a/manual/16-shell-functions.md b/manual/19-shell-functions.md similarity index 100% rename from manual/16-shell-functions.md rename to manual/19-shell-functions.md diff --git a/manual/17-tuis.md b/manual/20-tuis.md similarity index 87% rename from manual/17-tuis.md rename to manual/20-tuis.md index 91111bf7..4d4593ac 100644 --- a/manual/17-tuis.md +++ b/manual/20-tuis.md @@ -34,13 +34,17 @@ You start it (or reattach to your existing session) with `Super + Ctrl + Return` Omarchy has packaged this as _About_ in the Omarchy menu (`Super + Space`). +## Disk Usage + +When the drive fills up and you have no idea what's eating it, launch _Disk Usage_ from the app launcher (`Super + Space`). It's [dua](https://github.com/Byron/dua-cli) in interactive mode pointed at the whole file system, so you can walk down into whatever directory is the culprit, sorted biggest first, and delete from right inside it. + ## Cliamp [Cliamp](https://www.cliamp.stream/) is a retro terminal music player inspired by Winamp 2.x, complete with built-in radio stations for lo-fi beats. Launch it with `Super + Shift + Alt + M`, or from the Omarchy menu under _Apps_. Press `?` for the full keybinding list. ## What about Wi-Fi and Bluetooth? -You won't find TUIs for Wi-Fi and Bluetooth — those jobs belong to the Omarchy shell. Click the Wi-Fi icon in the top bar (or hit `Super + Ctrl + W`) to see networks and connect, and click the Bluetooth icon (or hit `Super + Ctrl + B`) to pair and connect devices. Networking itself is handled by NetworkManager, and there are `omarchy network` and `omarchy bluetooth` commands if you prefer the terminal. +You won't find TUIs for Wi-Fi and Bluetooth — those jobs belong to the Omarchy shell. Click the Wi-Fi icon in the top bar (or hit `Super + Ctrl + W`) to see networks and connect, and click the Bluetooth icon (or hit `Super + Ctrl + B`) to pair and connect devices. See [networking](34-networking.md) for the full story. ## Adding your own diff --git a/manual/18-guis.md b/manual/21-guis.md similarity index 68% rename from manual/18-guis.md rename to manual/21-guis.md index 160b349d..f5dfa8e8 100644 --- a/manual/18-guis.md +++ b/manual/21-guis.md @@ -1,5 +1,13 @@ # GUIs +## Files + +Files (Nautilus) is the graphical file manager. `Super + Shift + F` opens it, and `Super + Shift + Alt + F` opens it in the directory your terminal is sitting in, which saves a lot of clicking. `Ctrl + L` lets you type a path, and hitting `Space` on any file gives you a quick preview without opening anything. + +Plug in a USB stick or an SD card and it's mounted automatically, so it just shows up in the sidebar. For anything more involved — formatting a drive, checking SMART health, creating partitions — launch _Disks_ from the app launcher (`Super + Space`). + +Double-clicking follows sensible defaults: images open in imv, video in mpv, PDFs in Document Viewer, and plain text in Neovim. + ## Obsidian [Obsidian](https://obsidian.md/) is a free and highly extensible note taking application that uses simple Markdown files for storage. @@ -24,7 +32,7 @@ You start Pinta via the application launcher (`Super + Space`). ## Aether -[Aether](https://github.com/bjarneo/aether) is a theming application that can extract colors from a background image and turn them into a complete, cohesive theme. It's the easiest way to [make your own theme](37-making-your-own-theme.md). +[Aether](https://github.com/bjarneo/aether) is a theming application that can extract colors from a background image and turn them into a complete, cohesive theme. It's the easiest way to [make your own theme](43-making-your-own-theme.md). You start Aether via the application launcher (`Super + Space`). @@ -32,7 +40,18 @@ You start Aether via the application launcher (`Super + Space`). [LocalSend](https://localsend.org/) lets you send files to other devices on the same network running the app, like Apple's AirDrop. It's cross-platform, though, so you can send files to and from Windows, macOS, Android, iOS, and of course Linux. -You can open the LocalSend menu on `Super + Ctrl + S` or under _Trigger > Share_ in the Omarchy menu. +You can open the Share menu on `Super + Ctrl + S` or under _Trigger > Share_ in the Omarchy menu. It gives you four options: + +- **Clipboard** sends whatever you've copied as a text file. Great for getting a link or a snippet onto your phone without emailing yourself. +- **File** opens a file picker where you can select several at once. +- **Folder** sends an entire directory. +- **Receive** opens LocalSend proper so another device can send something to you. + +The same thing works from the terminal with `omarchy share clipboard`, `omarchy share file [path]`, and `omarchy share folder [path]`. Leave the path off and you get the picker. + +You can also send straight from the file manager: right-click any selection in Nautilus and pick _Send via LocalSend_. + +Omarchy's firewall is closed by default except for LocalSend's port, so this works out of the box on a fresh install. See [security](48-security.md). ## LibreOffice diff --git a/manual/22-browsers.md b/manual/22-browsers.md new file mode 100644 index 00000000..fdb37566 --- /dev/null +++ b/manual/22-browsers.md @@ -0,0 +1,39 @@ +# Browsers + +Omarchy ships with [Chromium](https://www.chromium.org/) as the default browser. It's the plain open-source build, themed to match the rest of your system, and it's what `Super + Shift + Return` opens and what every [web app](24-web-apps.md) runs inside. + +If Chromium isn't your taste, you're not stuck with it. Under _Install > Browser_ in the Omarchy menu you'll find Chrome, Edge, Brave, Brave Origin, Firefox, and [Zen](https://zen-browser.app/). Pick one and Omarchy installs it, sets up its policy directory, and applies your current theme to it. + +## Making one the default + +Installing a browser doesn't promote it. Once it's on the machine, go to _Setup > Defaults > Browser_ and pick it — the menu only lists browsers you actually have installed, and marks the current default with a check. + +From the terminal it's: + +```bash +omarchy default browser firefox +``` + +Run it with no argument and it tells you the current default. This sets the XDG handler, so it's not just Omarchy's hotkeys that follow along — anything that opens a link, from a chat app to a terminal command, goes to the browser you picked. + +## Copy URL and Download Video + +The Chromium-family browsers (Chromium itself, Chrome, Edge, and Brave) come with two Omarchy extensions that reach out of the browser and into the rest of your system. + +**Copy URL** puts the current tab's address on your clipboard with `Alt + Shift + L`. That's faster than clicking into the address bar and copying, and because it goes through the system clipboard rather than the browser's, you get an Omarchy notification confirming it and the URL is immediately available in [clipboard history](07-unified-clipboard-history.md) and every other app. There's a toolbar button too, if you prefer clicking. + +**Download Video** grabs the video playing on the page you're looking at with `Alt + Shift + D`. It hands the URL to [yt-dlp](https://github.com/yt-dlp/yt-dlp), so it works on far more than YouTube, and the download lands in `~/Videos`. Progress shows up in the same on-screen display that volume and brightness use, updating in place rather than stacking up notifications. Set `OMARCHY_YTDLP_DIR` if you'd rather the files went somewhere else — see the [FAQ](46-faq.md) for where to put environment variables. + +Both extensions talk to Omarchy through a small native messaging host, which gets installed for you along with the browser. That's the piece that lets a web page's video end up in your home directory and a URL end up in your clipboard manager, which a normal extension can't do on its own. + +These are Chromium-family only. Firefox and Zen don't get them. + +## Firefox and Zen + +Firefox and Zen are a different family, so they get different treatment: Omarchy installs a policies file for sensible defaults and switches them into native Wayland mode, which you want for fractional scaling and smooth trackpad scrolling. + +They don't get the Chromium extensions above, and they're not themed by Omarchy, so those parts of the experience are yours to set up. + +## Removing one again + +Anything you installed here can be taken back off under _Remove > Browser_. Chromium isn't in that list — it's part of the base system. diff --git a/manual/19-commercial-apps-services.md b/manual/23-commercial-apps-services.md similarity index 69% rename from manual/19-commercial-apps-services.md rename to manual/23-commercial-apps-services.md index 8457342b..12d643b8 100644 --- a/manual/19-commercial-apps-services.md +++ b/manual/23-commercial-apps-services.md @@ -8,6 +8,10 @@ Keeping your passwords in a password manager is a best practice. Doubly so if yo You start 1Password with `Super + Shift + /`. If it isn't installed yet, that hotkey kicks off the installation first (you can also use _Install > Service > 1Password_ from the Omarchy menu). The installer sets up the 1Password extension for Chromium as well. +## Bitwarden + +[Bitwarden](https://bitwarden.com/) is the open source alternative in the password manager space, with a free tier that covers most personal use. Install it with _Install > Service > Bitwarden_ from the Omarchy menu, which brings along the Bitwarden command line tool as well. + ## Spotify [Spotify](https://spotify.com/) is the world's most popular streaming music service. And the Linux application provides everything you'd expect, including offline playing. @@ -20,9 +24,13 @@ You start Spotify using `Super + Shift + M`. Like 1Password, the hotkey kicks of ## Tailscale -[Tailscale](https://tailscale.com/) is a mesh VPN that makes getting access to all your computers and servers over the internet securely super simple way. To set it up, select _Install > Service > Tailscale_ from the Omarchy menu. +[Tailscale](https://tailscale.com/) is a mesh VPN that makes getting access to all your computers and servers over the internet securely super simple. To set it up, select _Install > Service > Tailscale_ from the Omarchy menu. -Installing it also puts a Tailscale indicator in the bar, adds a web app for the Tailscale admin console, and sets up Taildrop. That means you can send files between your machines with `omarchy tailscale send `, and incoming files automatically land in `~/Downloads`. +It gets a panel in the bar, a web app for the admin console, and Taildrop for sending files between your machines — see [networking](34-networking.md). + +## ONCE + +[ONCE](https://once.com/) is 37signals' line of software you buy once and run on your own server, like the Campfire chat system. Select _Install > Service > ONCE_ from the Omarchy menu to install it, which enables its background service and drops you into the ONCE terminal interface to take it from there. ## NordVPN diff --git a/manual/20-web-apps.md b/manual/24-web-apps.md similarity index 100% rename from manual/20-web-apps.md rename to manual/24-web-apps.md diff --git a/manual/21-gaming.md b/manual/25-gaming.md similarity index 100% rename from manual/21-gaming.md rename to manual/25-gaming.md diff --git a/manual/22-filling-out-pdfs.md b/manual/26-filling-out-pdfs.md similarity index 100% rename from manual/22-filling-out-pdfs.md rename to manual/26-filling-out-pdfs.md diff --git a/manual/23-windows-vm.md b/manual/27-windows-vm.md similarity index 100% rename from manual/23-windows-vm.md rename to manual/27-windows-vm.md diff --git a/manual/24-other-packages.md b/manual/28-other-packages.md similarity index 100% rename from manual/24-other-packages.md rename to manual/28-other-packages.md diff --git a/manual/25-updates.md b/manual/29-updates.md similarity index 89% rename from manual/25-updates.md rename to manual/29-updates.md index d5aa8ca2..70391d6e 100644 --- a/manual/25-updates.md +++ b/manual/29-updates.md @@ -20,6 +20,10 @@ Finally, there's the dev channel, which links Omarchy directly to a git checkout You can switch between channels using _Update > Channel_ from the Omarchy menu (or `omarchy-channel-set` in the terminal). +### Firmware updates + +Your packages aren't the only thing that goes stale. Many laptops and peripherals ship BIOS, SSD, and dock firmware through the Linux Vendor Firmware Service, and _Update > Firmware_ in the Omarchy menu will fetch and install whatever your hardware has waiting. It installs `fwupd` the first time you run it. Plenty of firmware can only be written during a reboot, so don't be surprised to be asked for one. + ### Warning about direct pacman/yay updates If you're already familiar with Arch, you might be tempted to just run `pacman -Syu` or `yay -Syu` yourself, but if you do that, you'll miss the snapshot, migrations, and configuration updates that Omarchy runs together with new packages. That's why Omarchy will actually stop a direct system upgrade and point you to `omarchy update` instead. (If you really know what you're doing, the guard will tell you how to bypass it for a single transaction.) diff --git a/manual/26-dotfiles.md b/manual/30-dotfiles.md similarity index 66% rename from manual/26-dotfiles.md rename to manual/30-dotfiles.md index 3b99d727..11e0d762 100644 --- a/manual/26-dotfiles.md +++ b/manual/30-dotfiles.md @@ -20,6 +20,42 @@ Here's a list of the key files in `~/.config` and what they control: If you end up making a lot of changes to tweak your own setup, it's a good idea to backup all these dotfiles. [Stow is a great way to do that](https://www.youtube.com/watch?v=NoFiYOqnC4o). +### Starting your own apps with the session + +If you want something to run every time you log in — a sync daemon, a chat app, your own script — put it in `~/.config/hypr/autostart.lua`: + +```lua +o.launch_on_start("my-service") +``` + +That starts the command as part of the session, so it's properly cleaned up when you log out again. + +### Running scripts on system events + +Omarchy fires hooks at a handful of moments, and you can hang your own scripts off them. They live in `~/.config/omarchy/hooks/.d/`, one directory per event, and every executable file in there runs when the event happens: + +| Event | When it runs | +| ----- | ------------ | +| `post-boot` | Right after the desktop has started | +| `post-update` | During `omarchy update`, after packages and migrations | +| `pre-refresh-pacman` | Before `omarchy refresh pacman` re-syncs the package config | +| `theme-set` | After a theme change (theme name in `$1`) | +| `font-set` | After a font change (font name in `$1`) | +| `battery-low` | When the battery gets low (percentage in `$1`) | + +Each of those directories already holds a `.sample` file showing the shape of a hook — drop the `.sample` from the name to put it to work. To install a script you've written elsewhere, use `omarchy hook install post-boot ~/my-hook`, which copies it in and makes it executable. + +### Adding your own menu entries + +The Omarchy menu (`Super + Space`) can be extended with your own rows by editing `~/.config/omarchy/extensions/omarchy-menu.jsonc`. Entries are keyed by a dotted id, and the id is what places them in the tree, so `personal` shows up on the root menu and `personal.notes` shows up inside it: + +```jsonc +"personal": {"icon":"","label":"Personal"}, +"personal.notes": {"icon":"󰎞","label":"Notes","action":"omarchy-launch-editor ~/notes"}, +``` + +Reuse an existing id and you override that row instead of adding a new one. The file ships with all the available fields documented as comments. + ### Adding your own shell exports, functions, and aliases Omarchy ships with a bunch of ergonomic aliases and helpful functions, but it's very common to want to add your own. You should add both aliases, functions, and exports in `~/.bashrc`. This file will not be overwritten on updates. If you want to change any of the Omarchy defaults, you can also safely add them here. diff --git a/manual/31-shell-plugins.md b/manual/31-shell-plugins.md new file mode 100644 index 00000000..c5c95085 --- /dev/null +++ b/manual/31-shell-plugins.md @@ -0,0 +1,102 @@ +# Shell Plugins + +The Omarchy desktop runs as a single long-lived Quickshell process called `omarchy-shell`, and almost everything you see on screen is a plugin inside it. The bar is a plugin. So are the panels that drop down from it, the fullscreen overlays like the emoji picker and the clipboard manager, the Omarchy menu itself, the lock screen, the polkit dialog, and the headless services that watch your battery and warm your screen up at night. + +That's not just an implementation detail. It means you can turn pieces of the desktop off, swap them out, or write your own without touching a line of Omarchy's source. + +The first-party plugins ship with Omarchy and live in `$OMARCHY_PATH/shell/plugins/`. Anything you add yourself — your own experiments, or something you found on GitHub — lives in `~/.config/omarchy/plugins/`. Both are discovered the same way at startup; the only difference is where they sit on disk. + +## Seeing what you have + +``` +omarchy plugin list +``` + +That prints every discovered plugin with its id, whether it's enabled, whether it's first-party or third-party, its kinds, and its display name. Add `--json` if you're feeding it to something else. + +Plugin ids are namespaced. The built-ins all start with `omarchy.` — `omarchy.clock`, `omarchy.network`, `omarchy.notifications` — and that namespace is reserved, so a third-party plugin can never claim it. + +## Turning them on and off + +``` +omarchy plugin enable omarchy.tailscale +omarchy plugin disable omarchy.weather +``` + +Or use the menu: _Setup > Plugins_ has Enable, Disable, Add, Clone, and Remove, each with a picker that only offers the plugins that make sense for that action. + +Enabled state is stored in `~/.config/omarchy/shell.json`, and the rule differs slightly for the two kinds of plugin. A third-party plugin is enabled exactly when its id appears somewhere in that file — as a bar layout entry, as an entry in `plugins[]`, or as `bar.id`. First-party plugins that aren't bar widgets are the other way around: they're on by default and only turn off by being listed in `disabledPlugins[]`. + +A full bar plugin has no off state at all. There's always exactly one bar, so you replace it by enabling another one. Bar widget placement is covered in [the top bar](04-the-top-bar.md). + +## Adding a plugin from git + +A third-party plugin is just a git repo with a `manifest.json` at its root. + +``` +omarchy plugin add https://github.com/acme/omarchy-weather.git --enable +``` + +Before it does anything, it tells you plainly that plugins run as arbitrary, unsandboxed code inside your long-lived shell process, shows you the URL, and asks you to confirm. Take that seriously. A plugin isn't a config file — it's code that runs for as long as your session does, with everything your user account can reach. Only add repos you're willing to run, and read them before you enable them. + +Then it clones the repo into a staging directory, validates the manifest, refuses the install if another plugin already claims that id, and moves it into `~/.config/omarchy/plugins//`. Without `--enable` it asks whether you want it on now, and you can say no and go read the code first. It never runs anything from the plugin, never executes an install hook, and never asks for sudo — it clones files, checks the manifest, and flips a bit over IPC. + +Updating is a fast-forward pull of that same checkout: + +``` +omarchy plugin update acme.weather +omarchy plugin update +``` + +With no id it updates every git-managed plugin you have. It shows you the diff before applying it, refuses to update if you've got local changes it can't fast-forward past, and rolls back if the new revision fails validation. + +``` +omarchy plugin remove acme.weather +``` + +Removal disables the plugin first, then deletes it if it's a git checkout (the repo is still upstream) or unlinks it if it's a symlink. A hand-made plugin folder with no git repo gets moved to a timestamped backup inside the plugins directory instead of being deleted outright. + +## Cloning a built-in to modify it + +This is my favorite part. If you want to change how a built-in widget behaves, don't edit the files under `$OMARCHY_PATH` — those belong to the package and the next update will overwrite them. Clone it instead: + +``` +omarchy plugin clone omarchy.clock +``` + +That copies the whole plugin into `~/.config/omarchy/plugins/dhh.clock` (your username, not mine), renames it to "My Clock", enables it, and switches the shell over from the built-in to your copy — keeping an existing bar widget's position and settings. Add `--edit` to open the new directory in your `$EDITOR` right away, which is what the menu's _Setup > Plugins > Clone Plugin_ does for you. + +The username prefix keeps your clone's id yours, so sharing it doesn't collide with anyone else's. Calls made to the original built-in id get routed to your clone, so nothing that referred to `omarchy.clock` needs updating. And if you make a mess of it, `omarchy plugin remove dhh.clock` puts the built-in back. + +Saving a file anywhere under `~/.config/omarchy/plugins/` reloads the plugin code automatically, so you can leave the editor open and watch your changes land. + +## Writing your own + +A plugin is a directory with a `manifest.json` and some QML. The manifest declares `schemaVersion: 1`, an `id`, `name`, `version`, one or more `kinds`, and an `entryPoints` object pointing at the QML file for each kind: + +| Kind | What it is | +|------|------------| +| `bar-widget` | A component the active bar can drop into a section | +| `panel` | A persistent or summoned floating window | +| `overlay` | A fullscreen overlay | +| `menu` | A summoned menu surface | +| `service` | A headless singleton with no UI | +| `bar` | A full bar that replaces the built-in one | + +A plugin can declare several kinds at once — the media plugin is both a `service` and a `bar-widget`. Bar widgets get an extra `barWidget` block with a display name, a category, an optional `defaultSection`, and `allowMultiple`, which says whether it makes sense to have more than one on the bar. Most widgets set it to `false`; spacers and indicators set it to `true`. + +Before you publish anything, check it: + +``` +omarchy plugin validate ./my-plugin +``` + +That runs the same checks the shell does at load time: the schema version, the required fields, an id that isn't reserved, entry points that are safe relative paths and actually exist, an entry point for every kind you claimed, and no symlinks anywhere inside the folder. + +For the full picture, the source is the documentation: `shell/README.md` in the Omarchy repo covers the manifest schema, the shell's IPC contract, and the exact shape of `shell.json`, and `shell/plugins/README.md` lists every first-party plugin with its id, kinds, and entry points. + +## Sharing yours with the world + +Once you've made something you like, put it in a public git repo. That's the whole distribution mechanism — anyone can then run `omarchy plugin add` against your URL and have it running in seconds. + +To help people actually find it, list it at [omarchyplugins.com](https://omarchyplugins.com). That's the community directory of Omarchy shell plugins, and it's the first place to look when you're wondering whether someone has already built the widget you're about to write. Browse it before you start! diff --git a/manual/27-monitors.md b/manual/32-monitors.md similarity index 87% rename from manual/27-monitors.md rename to manual/32-monitors.md index 48cc2a12..314bdc3d 100644 --- a/manual/27-monitors.md +++ b/manual/32-monitors.md @@ -20,6 +20,16 @@ Changes to `GDK_SCALE` apply to applications started after the change (and GTK o You can also quickly cycle through the major monitor scaling ratios (1x, 1.25x, 1.6x, 2x, 3x, 4x) using `Super + /` to go higher and `Super + Alt + /` to go lower. If you have the default configuration, these changes will also persist past reboot. +### Making text bigger or smaller + +Monitor scaling changes the size of everything. If all you want is bigger or smaller _text_, there's a single knob for that: + +``` +omarchy display text size 14 +``` + +That takes a pixel size between 9 and 20, and moves the Omarchy shell, GTK applications, and your terminal together, so the whole desktop stays in proportion. Run it without an argument to see where you're at, and `omarchy display text size reset` to go back to the default. Foot is the one straggler: it has no way to reload its config, so running terminals keep their old size until you open a new one. + ### Extending and mirroring laptop displays When you connect an external screen to your laptop, the display is automatically extended. But you can change that to mirroring instead using _Trigger > Hardware_ in the Omarchy menu or `Super + Ctrl + Alt + Delete`. This is especially helpful if that external screen is a projector, and you want to show something while working. diff --git a/manual/28-keyboard-mouse-trackpad.md b/manual/33-keyboard-mouse-trackpad.md similarity index 100% rename from manual/28-keyboard-mouse-trackpad.md rename to manual/33-keyboard-mouse-trackpad.md diff --git a/manual/34-branding.md b/manual/34-branding.md deleted file mode 100644 index dbee7325..00000000 --- a/manual/34-branding.md +++ /dev/null @@ -1,27 +0,0 @@ -# Branding - -Omarchy allows you to set your company logo or personal image for both the boot unlock, the screensaver, and the about screen. - -### Boot unlock - -You can use `omarchy plymouth preview` to see what your custom logo and colors would look like. It takes a background color, a text color, a logo png, and a path for the preview image: - -``` -omarchy plymouth preview '#1d2021' '#ebdbb2' logo.png preview.png -``` - -Then apply the setup with `omarchy plymouth set '#1d2021' '#ebdbb2' logo.png`, which will also give the SDDM login screen the same colors and logo. If you want to revert, you can use `omarchy plymouth reset`. - - ![shopify-plymouth.jpeg](https://learn.omacom.io/u/shopify-plymouth-AjqlgW.jpeg) - -### Screensaver - -You can change the logo used for the screensaver under _Style > Screensaver_. It's an ASCII logo, so you can edit the text directly, but you can also upload a png or svg image, and we'll convert that to ASCII. It looks pretty cool. - - ![screensaver.gif](https://learn.omacom.io/u/screensaver-xDOE2Y.gif) - -### About screen - -The same can be done with the _About_ screen accessible from the Omarchy menu. Same options as with the screensaver under _Style > About_. - - ![about.png](https://learn.omacom.io/u/about-wi4tkl.png) diff --git a/manual/34-networking.md b/manual/34-networking.md new file mode 100644 index 00000000..4d39f622 --- /dev/null +++ b/manual/34-networking.md @@ -0,0 +1,45 @@ +# Networking + +Networking in Omarchy is handled by NetworkManager, and you drive it from the network icon in the [top bar](04-the-top-bar.md) or with `Super + Ctrl + W`. + +That panel scans for Wi-Fi networks, shows signal strength, and connects. Ethernet needs nothing at all — plug it in and it works. If you'd rather stay in the terminal, `nmtui` is one right-click away on the same icon, and there's an `omarchy network` command group too. + +## Sharing your Wi-Fi + +Rather than reading a long password out loud, run _Setup > Network > QR Code_ while you're on Wi-Fi. That puts a QR code on screen that any phone camera can scan to join. It's one of those things you'll use more than you'd expect once you know it's there. + +If you actually need the password itself, `omarchy network password ` prints it. + +## DNS + +Omarchy uses whatever DNS your network hands out over DHCP. You can override that for the whole machine under _Setup > Network > DNS_, where Cloudflare and Google are one click away. Pick _Custom_ to type in your own servers. + +From the terminal, `omarchy dns` prints the current provider and `omarchy dns Cloudflare` sets one. + +## Pinning the Wi-Fi band + +If your router puts 2.4GHz, 5GHz, and 6GHz on the same network name, your laptop will sometimes cling to the slow one. `omarchy network band` shows which band you're on, and `omarchy network band 5` pins it. Use `auto` to let it choose again. + +This pins the band rather than a specific access point, so you keep roaming between APs normally. + +## How fast is it? + +_Trigger > Speed Test > Network Speed Test_ measures your actual up and down speed with a pair of dials. From the terminal it's `omarchy network speedtest down` or `up`. (There's a disk speed test sitting next to it in that menu, if you're benchmarking the other bottleneck.) + +## The firewall + +The firewall is on by default and blocks all incoming traffic, with one exception: port 53317, so [LocalSend](21-guis.md) works out of the box. + +SSH is off until you turn it on with _Setup > Security > SSHD_, which starts the daemon, opens port 22 rate-limited against brute force, and authorizes a key. Docker is locked down too, so containers can't accidentally expose themselves to the world. See [security](48-security.md) for the whole story. + +## Tailscale + +[Tailscale](https://tailscale.com/) is a mesh VPN that makes reaching all your computers and servers over the internet simple and secure. Install it with _Install > Service > Tailscale_. + +That gives you a Tailscale panel in the bar, which connects and disconnects the tailnet, switches accounts, and picks an exit node — your own machines and Mullvad regions both show up in the list. It also browses your machines, and that's where Taildrop lives: select a machine and press `s` to send it files, or `c`, `n`, and `d` to copy its IP, name, or full DNS name. The terminal equivalent is `omarchy tailscale send [file...]`, and files sent to you land in `~/Downloads` automatically. + +Installing it also adds a web app for the Tailscale admin console. + +## When it stops working + +Before rebooting, try restarting the offending piece on its own. _Update > Hardware_ has Wi-Fi, Bluetooth, Audio, and Trackpad, and reloading one of those clears up most "it worked five minutes ago" situations. See [troubleshooting](45-troubleshooting.md). diff --git a/manual/29-system-sleep.md b/manual/35-system-sleep.md similarity index 61% rename from manual/29-system-sleep.md rename to manual/35-system-sleep.md index 0ac029f1..df6c8174 100644 --- a/manual/29-system-sleep.md +++ b/manual/35-system-sleep.md @@ -2,6 +2,12 @@ Omarchy enables suspend and hibernation by default, but if you're having issues with either on your machine, you can toggle them off. +### Power profiles + +On a laptop, Omarchy remembers your power profile separately for plugged in and running on battery, and switches between the two as you plug and unplug. Out of the box that means performance on AC and balanced on battery. + +You can see what your machine offers with `omarchy powerprofiles list`, and set the one you want for the state you're currently in with `omarchy powerprofiles set autodetect power-saver`. To set the other state without unplugging anything, name it directly: `omarchy powerprofiles set battery power-saver`. Whatever you pick is what you'll get back the next time you're in that state. + ### Toggle suspend You toggle suspend by running `omarchy toggle suspend` from the terminal. That just reveals/hides the option under _System_ (or `Super + Esc`), and then you can see if it works consistently on your system. If not, you can hide it again with the same command. diff --git a/manual/30-hardware-authentication.md b/manual/36-hardware-authentication.md similarity index 100% rename from manual/30-hardware-authentication.md rename to manual/36-hardware-authentication.md diff --git a/manual/31-fonts.md b/manual/37-fonts.md similarity index 100% rename from manual/31-fonts.md rename to manual/37-fonts.md diff --git a/manual/32-backgrounds.md b/manual/38-backgrounds.md similarity index 100% rename from manual/32-backgrounds.md rename to manual/38-backgrounds.md diff --git a/manual/33-prompt.md b/manual/39-prompt.md similarity index 100% rename from manual/33-prompt.md rename to manual/39-prompt.md diff --git a/manual/40-branding.md b/manual/40-branding.md new file mode 100644 index 00000000..59c0da4f --- /dev/null +++ b/manual/40-branding.md @@ -0,0 +1,43 @@ +# Branding + +Omarchy allows you to set your company logo or personal image for both the boot unlock, the screensaver, and the about screen. + +### Boot unlock + +You can use `omarchy plymouth preview` to see what your custom logo and colors would look like. It takes a background color, a text color, a logo png, and a path for the preview image: + +``` +omarchy plymouth preview '#1d2021' '#ebdbb2' logo.png preview.png +``` + +Then apply the setup with `omarchy plymouth set '#1d2021' '#ebdbb2' logo.png`, which will also give the SDDM login screen the same colors and logo. If you want to revert, you can use `omarchy plymouth reset`. + + ![shopify-plymouth.jpeg](https://learn.omacom.io/u/shopify-plymouth-AjqlgW.jpeg) + +### Screensaver + +You can change the logo used for the screensaver under _Style > Screensaver_. It's an ASCII logo, so you can edit the text directly, but you can also hand it a png or svg image, and we'll convert that to ASCII. It looks pretty cool. + + ![screensaver.gif](https://learn.omacom.io/u/screensaver-xDOE2Y.gif) + +There are three entries in that menu: + +- **Edit Text** opens `~/.config/omarchy/branding/screensaver.txt` in your editor. Type or paste whatever you like — ASCII art, your name, a rude word. Save and quit, and the screensaver fires up immediately so you can see it. +- **Set From Image** opens a file picker for a png or svg, converts it to ASCII, and shows you the result. Logos with a clear silhouette work far better than photos. +- **Restore Default** puts the Omarchy logo back. + +### About screen + +The same three options are under _Style > About_ for the _About_ screen you get from the Omarchy menu, and they work identically — the file is `~/.config/omarchy/branding/about.txt`, and the About window pops up after each change. The About art is converted to a smaller size than the screensaver's, since it has to fit in a window rather than fill your display. + + ![about.png](https://learn.omacom.io/u/about-wi4tkl.png) + +### Converting images yourself + +Both of the _Set From Image_ options are just calling `omarchy transcode ascii`, which you can run directly if you want control over the conversion: + +``` +omarchy transcode ascii ~/logo.svg ~/.config/omarchy/branding/screensaver.txt --width 100 +``` + +It takes `--width` and `--height` in terminal columns and rows, a `--mode` of either `braille` (the default, and much finer) or `block`, a `--threshold` percentage for deciding which pixels count as part of the logo, and `--invert` for when your logo is light on a dark background. If a conversion comes out as a blob, the threshold is usually the knob to turn. diff --git a/manual/35-common-tweaks.md b/manual/41-common-tweaks.md similarity index 100% rename from manual/35-common-tweaks.md rename to manual/41-common-tweaks.md diff --git a/manual/36-extra-themes.md b/manual/42-extra-themes.md similarity index 100% rename from manual/36-extra-themes.md rename to manual/42-extra-themes.md diff --git a/manual/37-making-your-own-theme.md b/manual/43-making-your-own-theme.md similarity index 70% rename from manual/37-making-your-own-theme.md rename to manual/43-making-your-own-theme.md index 8e58f97d..1ec10bd3 100644 --- a/manual/37-making-your-own-theme.md +++ b/manual/43-making-your-own-theme.md @@ -18,8 +18,14 @@ If you'd like to color-match the file manager icons to your theme, add a file ca Themes supplied with `unlock.png` and `preview-unlock.png` images will be listed under _Style > Unlock_. Your `unlock.png` should preferably be a transparent png. And you can create the preview image using `omarchy plymouth preview`. +### Theming apps Omarchy doesn't cover + +If you use an app that isn't in that list, you can teach Omarchy to theme it yourself with a template. Drop a file in `~/.config/omarchy/themed/` named after the config it generates plus a `.tpl` extension, and write the config with `{{ background }}`, `{{ foreground }}`, `{{ accent }}`, `{{ red }}`, `{{ color0 }}` through `{{ color15 }}`, and the rest of the palette as placeholders. Every time you switch themes, the file is regenerated with that theme's colors. + +There's a fully commented `alacritty.toml.tpl.sample` in that folder to copy from — it lists every variable you can use, plus the `_strip` and `_rgb` modifiers for apps that want their colors without the `#` or as decimal RGB. Your templates take priority over Omarchy's own, so you can also use this to override how a built-in app gets themed. + ### Distributing your theme If you want to distribute your theme so others can use it, you need to put it on a public git server, like GitHub. Then people can install it using _Install > Style > Theme_ in the Omarchy menu using that URL. It's recommended that you follow the naming convention of `omarchy-[themename]-theme`, as the theme will show correctly as just `[themename]` in the theme selection menu after installation. -You can have your theme added to [the extra themes page](36-extra-themes.md) by pinging @tahayvr on [the #omarchy Discord](https://discord.gg/tXFUdasqhY). +You can have your theme added to [the extra themes page](42-extra-themes.md) by pinging @tahayvr on [the #omarchy Discord](https://discord.gg/tXFUdasqhY). diff --git a/manual/38-mac-support.md b/manual/44-mac-support.md similarity index 100% rename from manual/38-mac-support.md rename to manual/44-mac-support.md diff --git a/manual/39-troubleshooting.md b/manual/45-troubleshooting.md similarity index 75% rename from manual/39-troubleshooting.md rename to manual/45-troubleshooting.md index 371b44d0..9eda0c98 100644 --- a/manual/39-troubleshooting.md +++ b/manual/45-troubleshooting.md @@ -2,17 +2,17 @@ ### I broke my system with an update! -First try to [rollback your system](41-system-snapshots.md) the version before your recent update. If that doesn't work, use `omarchy-debug` to share with your problem on #omarchy-help in the Discord. And if all that fails, you can reinstall the defaults configs and packages using `omarchy-reinstall`. +First try to [rollback your system](47-system-snapshots.md) the version before your recent update. If that doesn't work, use `omarchy-debug` to share with your problem on #omarchy-help in the Discord. And if all that fails, you can reinstall the defaults configs and packages using `omarchy-reinstall`. ### Why are some apps so large on my display? -Omarchy assumes a 2x high-resolution display, which requires setting `GDK_SCALE` to 2 in `~/.config/hypr/monitors.lua`. But if you're on a 1x display, you can change `local omarchy_gdk_scale = 2` to 1 (and then restart any app that's oversized). See [the manual on monitors](27-monitors.md). +Omarchy assumes a 2x high-resolution display, which requires setting `GDK_SCALE` to 2 in `~/.config/hypr/monitors.lua`. But if you're on a 1x display, you can change `local omarchy_gdk_scale = 2` to 1 (and then restart any app that's oversized). See [the manual on monitors](32-monitors.md). For Spotify, you can use `Ctrl + Minus` to shrink the UI (and `Ctrl + Plus` to make it bigger). ### Why isn't Caps Lock working? -In Omarchy, Caps Lock has been designated to be the xcompose key. That's how you get [quick emojis](05-hotkeys.md#quick-emojis) and [other autocompletions](05-hotkeys.md#quick-completions) done. If you really miss using Caps Lock, you can remap the xcompose key to something else by editing `~/.config/hypr/input.lua`, like setting it to the right alt key: +In Omarchy, Caps Lock has been designated to be the xcompose key. That's how you get [quick emojis](06-hotkeys.md#quick-emojis) and [other autocompletions](06-hotkeys.md#quick-completions) done. If you really miss using Caps Lock, you can remap the xcompose key to something else by editing `~/.config/hypr/input.lua`, like setting it to the right alt key: ``` hl.config({ @@ -22,6 +22,10 @@ hl.config({ }) ``` +### My Wi-Fi, Bluetooth, audio, or trackpad just stopped working + +Before you reboot, try restarting the offending subsystem on its own. _Update > Hardware_ in the Omarchy menu has Wi-Fi, Bluetooth, Audio, and Trackpad, and reloading one of those clears up the majority of "it worked five minutes ago" situations — a Bluetooth headset that won't reconnect, a trackpad that went dead after a suspend, sound that vanished when you unplugged a monitor. + ### Why are my external speakers not playing? Probably because they're not set as the primary output. Click on the speaker icon on the right side of the bar, and it'll open the volume popup where you can pick the output device (and mix per-app volumes too). diff --git a/manual/40-faq.md b/manual/46-faq.md similarity index 64% rename from manual/40-faq.md rename to manual/46-faq.md index 6a462f66..a8f7aa41 100644 --- a/manual/40-faq.md +++ b/manual/46-faq.md @@ -26,6 +26,26 @@ omarchy bar set omarchy.clock format "dddd h:mm AP" This will display Sunday 10:55 AM. +### How do I change my timezone? + +Run _Update > Timezone_ in the Omarchy menu and pick from the list. If the timezone is right but the clock itself has drifted, _Update > Time_ restarts the time synchronization for you. + +### How do I change my DNS, share my Wi-Fi, or check my connection speed? + +Those all live in [networking](34-networking.md). + +### How do I check how fast my disk is? + +_Trigger > Speed Test > Disk Speed Test_ measures live read and write speed on your drive, or `omarchy disk speedtest` from the terminal. + +### Why can't I sign into my Google account in Chromium? + +The plain open source Chromium build doesn't ship with the OAuth credentials that Google requires for account sign-in. Run _Install > Service > Chromium Account_ in the Omarchy menu to add them, restart the browser, and the sign-in will go through. + +### How do I add a printer? + +Printing is set up and running out of the box, so a printer on your network is usually already discovered. Launch _Print Settings_ from the app launcher (`Super + Space`) to see what's there, add one by hand, or set the default. Printing to a PDF file works without any printer at all. + ### How do I change where screenshots or screenrecordings are saved? If you want screenshots to be saved to `~/Pictures/Screenshots` instead of just `~/Pictures`, you can add this to a file under `~/.config/uwsm/env.d/` (like `~/.config/uwsm/env.d/capture`): @@ -52,8 +72,8 @@ Run _Remove > Package_ to see every package that's installed. Then you can selec And you can use _Remove > Web App_ from the Omarchy menu to remove any of the preinstalled web apps you don't want. -Or run _Remove > Preinstalls_ to sweep out all the preinstalled extras — web apps, TUIs, and optional applications — in one go. +Or run _Remove > Preinstalls_ to sweep out all the preinstalled extras — web apps, TUIs, and optional applications — in one go. The hotkeys that launched them go away with them, so you're left with a clean slate of bindings to fill with your own in `~/.config/hypr/bindings.lua`. --- -For errors and broken bits, see [the Troubleshooting section](39-troubleshooting.md). +For errors and broken bits, see [the Troubleshooting section](45-troubleshooting.md). diff --git a/manual/41-system-snapshots.md b/manual/47-system-snapshots.md similarity index 70% rename from manual/41-system-snapshots.md rename to manual/47-system-snapshots.md index 05b8b6ed..c0a9ae4a 100644 --- a/manual/41-system-snapshots.md +++ b/manual/47-system-snapshots.md @@ -17,3 +17,9 @@ This will restore your root filesystem, but not your `/home`. So it works for re This also means that your `~/.config` directory is kept as-is. So if you're rolling back to an earlier version of a library or application that stores configuration files in a new format, you'll have to sort that out manually. _Note: This feature is only available on installations using the Limine boot loader, which has been the default since Omarchy 2.0. It's not available if you're on GRUB or systemd-boot._ + +### Skipping the boot menu + +If you never touch the boot menu and just want the machine to go straight to the decryption screen, run _Setup > Direct Boot_ in the Omarchy menu. That adds an EFI entry pointing directly at Omarchy, so the firmware boots it without stopping at Limine. + +The trade-off is the one mentioned at the top: with direct boot on, getting to a snapshot means picking Limine from your BIOS boot menu first. Run _Setup > Direct Boot_ again to remove the entry and go back to booting through Limine. Some firmware doesn't take kindly to custom EFI entries, so the setup refuses to run on American Megatrends and Apple firmware. diff --git a/manual/42-security.md b/manual/48-security.md similarity index 71% rename from manual/42-security.md rename to manual/48-security.md index d9e0fde9..7c091303 100644 --- a/manual/42-security.md +++ b/manual/48-security.md @@ -8,6 +8,16 @@ Omarchy takes security extremely seriously. This is meant to be an operating sys 4. *Omarchy maintains its own packages and mirror*: Omarchy only relies on packages from Arch's own core/extra/multilib repositories and its own Omarchy Package Repository by default. You can install software directly from AUR, but the base install doesn't — only a few optional installs, like the third-party browsers, pull from the AUR. 5. *Cloudflare protects us from DDoS*: All the Omarchy distribution infrastructure — the ISOs, the Omarchy packages, the Arch mirror — is protected behind Cloudflare's formidable DDoS shield and hosted on their CDN. This provides superb availability. +## Changing your passwords + +You have two passwords on an encrypted install: the one that unlocks the drive at boot, and the one you log in and `sudo` with. Both can be changed under _Update > Password_ in the Omarchy menu — _Drive Encryption_ for the first, _User_ for the second. Changing the drive password asks for the current one first, so have it handy. + +## Passwordless sudo + +Sometimes you want `sudo` to stop asking, most often when an AI agent is doing a long stretch of system work for you. _Setup > Security > Passwordless Sudo_ turns that off for 15 minutes and then puts it back automatically. Run it again before the timer runs out to end it early, and pass your own number of minutes with `omarchy-sudo-passwordless 30` if 15 isn't enough. + +Be clear-eyed about this one: while it's on, anything running as your user can do anything as root without being asked. That's the whole point, and it's also the whole risk. + ## Signing Keys The public key for all ISO signatures and Omarchy repo package is `40DFB630FF42BCFFB047046CF0134EE680CAC571` ([verify at openpgp.org](https://keys.openpgp.org/search?q=pkgs%40omarchy.org)). The `omarchy/omarchy-keyring` package contains this as well and will be used to rollout any potential updates seamlessly. diff --git a/manual/43-omarchy-on.md b/manual/49-omarchy-on.md similarity index 100% rename from manual/43-omarchy-on.md rename to manual/49-omarchy-on.md diff --git a/manual/44-dual-boot-install.md b/manual/50-dual-boot-install.md similarity index 100% rename from manual/44-dual-boot-install.md rename to manual/50-dual-boot-install.md diff --git a/manual/45-unattended-installs.md b/manual/51-unattended-installs.md similarity index 100% rename from manual/45-unattended-installs.md rename to manual/51-unattended-installs.md