# omabox commands: every command and option

This is https://omabox.app/commands as Markdown, for agents. Every page: https://omabox.app/llms.txt

**Every omabox command, as the CLI prints it.**

Read from `omabox help` at [omabox 1.4.1](https://github.com/diogochaves/omabox/releases/tag/v1.4.1) when this site was built, so the options match the omabox you install. Built for agents to drive; every command is yours to type too.

## The agent drives its box the way you drive yours.

Launch, type, click, wait and look, with commands that say what happened. Peek shows where the agent clicks and what it types, over the view only, never in its screenshots.

### Your projects stay as they are

The skill maps what your project's instructions say to the same thing in a box.

| Your project says | The agent runs |
| --- | --- |
| `./build/app` | `omabox run -d -- ./build/app` |
| `grim out.png` | `omabox shot -o out.png` |
| `hyprctl -j clients` | `omabox hyprctl -j clients` |
| `ctest --test-dir build` | `omabox run -- ctest --test-dir build` |
| `omarchy-theme-set gruvbox` | `omabox run -- omarchy-theme-set gruvbox` |

## What your scripts can rely on.

omabox is mostly used by agents, which read its warnings; a script or CI reads exit codes and `--json`. From 1.0, within 1.x:

### Kept · Or only added to

Exit codes, and every `--json` field: its name, type and meaning. New fields may come, so read the ones you need by name.

- 0: done, or the condition held
- 1: it ran and failed, or the answer is no
- 2: called wrongly
- 124: not in time
- 125: `run`: omabox's own failure, never the command's

### Warned · Changed only after a warning

Commands, options, config keys and `OMABOX_*` variables. The old form works for one more minor release, with `omabox: deprecated:` on stderr naming the new one. `OMABOX_STRICT=1` refuses it at once, for CI.

```
$ OMABOX_STRICT=1 omabox check run -- ./scenario.sh
```

### Carried · Saves and baselines

A save made by a 1.x starts with any later 1.x. A `check` baseline approved by a 1.x compares with any later 1.x, or is refused (“approve again”), never compared wrongly.

### Not covered · What can still move

Message wording, help text, defaults, and what Hyprland and other programs report through omabox.

```
$ omabox help exit-codes
```

Every code, what it means, in every command.

## Every command, by what it's for.

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

### Start and end boxes

#### omabox up

Start a box: headless and invisible unless you ask for a window, any screen size or several monitors, on the theme you name, with your plugins, an isolated network or a save to start from.

Examples:

```
$ omabox up
$ omabox up --size 2560x1440@144 --plugin ~/code/myplugin
$ omabox up --monitor 1080x1920 --monitor 2560x1440,scale=1.6,below
$ omabox up --theme-dir ~/code/my-theme --theme my-theme
$ omabox up --net isolated --allow 8081
```

```
omabox up [NAME] [--size WxH[@HZ][,scale=S]|host] [--interactive] [--plugin PATH|ID]... [--overlay DIR]...
          [--ro-bind DIR[:DEST]]... [--seed SRC:DEST]... [--net isolated [--allow PORT,...] [--addr ADDR]...|host]
          [--env KEY=VAL]...
          [--no-seed extensions,fonts]                 your plugins' settings files, your fonts left on the desk
          [--theme-dir DIR]...                         a theme you are editing, live, in the box's themes/
          [--theme NAME]                               start on that theme, not your desktop's current one
          [--monitor WxH[@HZ][,scale=S][,right|below|X,Y]]...     more monitors
          [--idle DURATION] [--stock-bar] [--systemd] [--xwayland] [--autoreload] [--no-shell] [--from SAVE]
          [--desk-shell]                               your desktop's whole shell: every plugin, shell.json, their files
          [--audio] [--polkit]                         its own PipeWire (a silent mic); a polkit agent can register (polkit ask)
          [--no-pointer] [--dnd] [--no-dock]           no pointer (pointer show); Do Not Disturb on; 4.5's dock off
          [--stock | --clean [--keep animations,bar,clock,fonts,identity,locale,pointer,wallpaper]]   a new user's look; --clean: frozen too
          [--hyprland PATH]                            a Hyprland build or folder of yours, not the installed one
          [--quickshell PATH]                          a Quickshell build of yours for the box's shell
          [--omarchy DIR | --desktop plain|desk [--shell CMD]]   an Omarchy tree (a checkout); plain: nothing of Omarchy's, CMD its shell; desk: plain at your HOME's path
          [--workspace WS] [--confirm-close | --no-confirm-close]      (interactive)
          [--new]                                      start it under a free name, box-1, box-2, ... (printed)
          [--json]                                     the box as ls --json lists it, on stdout
```

`omabox help up` adds:

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Every box has its own network (pasta): by default the internet, the LAN and your servers. Across the box boundary use 127.0.0.1, not localhost; a box's servers appear on your 127.0.0.1 about a second after they listen, one box per port (a box server on a port the host or another box has fails to start, address in use; of two started within a second, only one gets it there: `omabox ports` names the holders). --net isolated: a loopback and the --allow ports only, which are for reaching those host ports from the box: pasta listens on each in the box, so a box server on one fails, address in use (`ports`: allowed); serve on another; --addr ADDR (repeatable) puts an address on that loopback, for an app that wants a peer from a non-local address: one in a documentation range (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32). A server on 203.0.113.10 sees a client bound to 203.0.113.11 come from there. --net host (asked for by name only; no config picks it): your host's network itself, no pasta, for a tool that scans the real LAN. The box keeps its own seat, session bus, runtime dir and HOME, but its servers take your host's real ports (they collide with your services and other host boxes; nothing is forwarded, `ports`: host-net), it sees your real interfaces and its ARP and ICMP reach your LAN. Not for code you do not trust. Refused with --allow, --addr, --xwayland (its X server would be your host's), --desktop desk, inside ai-jail, and while protect-ports names a port.

`run` starts the command with the box's environment, not yours: --pass VAR hands it one of your variables (a password too: never on a command line); --env-file FILE hands it a file's KEY=VAL lines (a dev.env: read as data, nothing expanded; --pass wins); `keys --pass VAR` types one (never `-t` for a secret: the process list shows it). `keys -t` and `keys --pass` type newline and tab (Return, Tab); any other control character is refused (exit 2); a value's one trailing \r is dropped. --env KEY=VAL is the box session's, on `up` (and a throwaway `run`'s box); `run --env` on a box that is up hands it to the command, as --env-file does (--pass wins). Never what the session sets itself (PATH, HOME, XDG_RUNTIME_DIR, XDG_*_HOME, WAYLAND_DISPLAY, DISPLAY, HYPRLAND_INSTANCE_SIGNATURE, LD_PRELOAD, OMABOX_BOX...), by any of them.

--seed SRC:DEST: a file or folder of yours copied into the box HOME at DEST (.config/x or ~/.config/x) before its session starts, for a plugin that reads its config once at start; the same refusals as --ro-bind (no secret stores; nothing in ~/.config/omarchy but plugins/ and themes/). A copy: the box's changes stay in the box; a link already in DEST is replaced, never written through. Never into a --plugin's or --theme-dir's folder there (refused: it would replace the plugin or theme): write the file in that folder instead.

--no-seed extensions: the box starts without your ~/.config/omarchy/extensions (the plugins' settings files, the menu's extension), with a new Omarchy user's (/etc/skel's; a --from save's own stay). Otherwise `up` copies it, and says each file a --plugin's code names there ("seeded extensions/NAME.json from your desk"): that plugin starts on your desk's settings, an on/off switch in them too. --no-seed fonts: the box starts without your fonts. Otherwise ~/.local/share/fonts and ~/.fonts are mounted read-only at the same place in the box HOME (`ls --json`: desk_fonts), so a theme's or a plugin's own faces draw as on your desk (not in a --stock box, nor a --clean one unless --keep fonts; nor when the box HOME has its own folder there, a --from save's or a --seed's: it keeps that one). A link in them that leads out of them is not in the box (said). Comma-separated, repeatable.

--theme-dir DIR: a theme you are editing, live: the box HOME's ~/.config/omarchy/themes/NAME (DIR's name) is a link to DIR at its own path, in place of the copy `up` makes of each of your themes. The box has DIR there when it is in the repo you run from, a same-path --ro-bind or an --overlay; any other DIR is mounted read-only there, refused as --ro-bind's are. omarchy-theme-set NAME in the box applies it, as it is then.

--theme NAME: the box starts on that theme (Omarchy's, one of yours or a --theme-dir one; checked before anything is made), not your desktop's current one: omarchy-theme-set NAME runs in the box before its Hyprland and bar start, so a test gets the same look whatever your desktop is on (its background: your own first for NAME, else the theme's; with --stock the theme's). Over a --from save's look too. `up` again with another is refused.

--stock-bar: Omarchy's default bar (its shell.json, no shell.toml), not a copy of yours: for shots, sizes and colours as most people see them. --theme leaves your bar as it is; without this `up` says when that bar is not Omarchy's ("seeded the bar from your desk: its shell.json layout and shell.toml [bar]"). Plugins are placed as without it. --stock: the rest of a new user's desktop too.

--no-shell: Hyprland only, no Omarchy shell (faster; no bar, tray or notifications). --desktop plain (#247): the box's Hyprland runs omabox's own small config (Hyprland's defaults, your   keyboard layout from /etc/vconsole.conf, SUPER+RETURN a terminal, SUPER+W closes) and sees an empty   /usr/share/omarchy, as on a machine without Omarchy: no shell but --shell's, and a HOME with none of   your Omarchy look (git's name and email only). --plugin, --theme, --theme-dir, --stock-bar, --stock,   --desk-shell, --omarchy, --dnd and --no-dock need Omarchy and are refused, as are the dnd, dock and   plugin commands on the box. Without --desktop: `omabox config desktop`'s, else omarchy where Omarchy   is installed and plain where it is not (up says so; doctor and setup test the same); --omarchy DIR   is an Omarchy box. ls says a plain box's desktop (and shell) under its line. --desktop desk (#321): your own desktop in a box, its HOME at your HOME's path ($HOME in the box is   yours), so what names your paths finds the box's: still the fake HOME, never your files (but the   repo, --ro-bind, --seed's and the copy of your desktop). From the host it is <dir>/home, as any   box's; a path under your HOME in a command is the box HOME's there, not yours (run says so). A   mount (--ro-bind, --overlay) goes inside that HOME, never at it or above it, over omabox's own   files in it, nor through a link in it. up copies in your ~/.config/hypr (links followed, as   copies), the config and state of the shell it finds, and the images they name, before --seed's;   never a secret store or what looks like a key, capped, what it left out said (box.json desk_copy).   It needs a Lua config (a hyprland.conf alone is refused: hyprctl eval refuses it). Its base is your   desk's: Omarchy's (Omarchy here and your hypr/hyprland.lua loading it: an Omarchy box, its shell   Omarchy's with your plugins and shell.json, as --desk-shell copies them; it takes --plugin,   --theme, --theme-dir, --dnd, --no-dock and --omarchy, refuses --stock, --stock-bar and --keep),   else plain. Its Hyprland runs your copied hyprland.lua; what it starts goes through an autostart   policy (idle and lock daemons, your systemd session, system-bus applets, what the box runs itself   are dropped; binds run as on your desk), each decision a line of `omabox log autostart`. Its idle is   held off (tools/idlehold): your shell's idle timeouts never lock or blank it. On a plain base its   shell is the one your config starts (DMS, Noctalia, Caelestia, Waybar, a Quickshell config), run in   the box's shell slot as --shell's: up waits for it and says which, and ls, pid shell, log shell and   restart-shell work on it; a second shell your config starts is dropped. --shell CMD runs another in   its place, --no-shell none; a config that starts none omabox knows fails up, saying so. Refused   with --desk-shell (part of it; alone it still works, with a note), --clean (the path carries your   login name) and inside ai-jail (not yet); `omabox config desktop` does not take desk yet, and   `check run --desktop desk` is refused (a check needs the same box every run). --shell CMD (#247, plain only): the box's shell is CMD (`dms run`, `qs -p DIR`, `caelestia shell   -d`), run by sh in the session; the shell is all CMD starts (#438): a launcher may start it and   exit, and the shell is gone once nothing of it is left. up waits until one of its processes draws   a layer (OMABOX_READY_TIMEOUT), says when it exits or crashes on the way; log shell is its output,   restart-shell stops all of it and starts CMD again, a Quickshell crash of its config is the   shell's. An app the shell starts itself counts as the shell (not one through `hyprctl dispatch   exec`). --quickshell PATH: the build is CMD's `qs` and `quickshell` (on the session's PATH).

--stock: Omarchy as a new user sees it, for a showcase or a shot for someone else: Omarchy's bar (--stock-bar) on tokyo-night (or --theme) with the theme's own wallpaper (never yours for it), English (en_US.UTF-8, else C.UTF-8) in UTC for the whole session, and nothing of your desk's look: not your terminal configs and terminal choice, branding, themes (but the one --theme names, when it is yours and not Omarchy's), wallpapers, plugins' settings (as --no-seed extensions), Hyprland toggles or fonts; a new user's HOME (/etc/skel's) instead. The clock, pointer, network and animations are as in any box; --plugin, --theme-dir and the rest work on top (`ls --json`: stock, a clean box's too). Your git name and email stay (git config --global user.name and user.email, so a commit in the box works): a shot of a git log shows them. Over a --from save, the save's HOME stays as saved (said); the bar, theme and locale are stock. Not with --desk-shell.

--clean: --stock plus the run-to-run freezes, a desktop where only what is tested moves, for shots compared across runs (`check`): a #ff00ff wallpaper (no theme has it: any of it inside a window or the bar is a hole), the bar's clock frozen at "Friday 12:00" (in its place, at its width), no pointer, no network (--net connected gives it back), animations off (over reloads too), and no name of yours: the user is `user` (no full name) and the host `omabox`. --keep LIST takes any of animations, bar (yours), clock, fonts (yours), identity (your user and host names), locale (yours and your timezone), pointer, wallpaper (the theme's) back. A theme set later in the box brings that theme's wallpaper. On a plain box: no bar, theme or clock (--keep bar and clock refused), and the sentinel is its Hyprland's background colour (misc:background_color), not a wallpaper.

--audio: the box's own PipeWire, WirePlumber and pipewire-pulse (PipeWire and Pulse apps both play), its only devices a speaker nobody hears (omabox-speaker, a null sink: the default output) and a silent microphone (omabox-mic, the default input). Nothing reaches your audio: a box has no /dev/snd and its own runtime dir (its sockets, never yours). `audio` says whether the box made a sound, `record --audio` puts it in the video (AAC). Logs: `log audio`. Without it a box has no audio.

--polkit: a polkit agent in the box (the shell's polkit plugin, a copy of it under test, a GTK or Qt agent) registers and is asked, as on a desktop, and the end of each request is the agent's own. A box has no system bus and no logind session, and never gets yours: it gets a system bus of its own where only polkit's name can be owned, by a stand-in authority, which keeps the agents as polkitd does (one per session, dropped when they leave the bus) and makes a request only when `polkit ask` does. In place of PAM it answers polkit's agent helper with a password prompt, and takes the one password `ask --accept` names (a test's, never yours). It decides nothing for any service: pkexec, pkcheck and mechanisms get no answer from it. The bus is the box's (its processes share one uid, so one can answer in the stand-in's place): what `polkit` prints of it is bounded and plain. The box's processes are in a session named "omabox" (XDG_SESSION_ID). Logs: `log polkit`.

--autoreload: the box's Hyprland reloads its config when a file it loaded changes, as a desktop's does; a box turns that off, so an update of omabox or Omarchy leaves it as it is. For a project that must see what a file change does (a helper rewriting a file the config loads, on a Hyprland event, reloads for ever). Its config is still the box's own copy; an Omarchy update reloads it too.

--plugin PATH|ID: a shell plugin, read-only, enabled where its manifest says; `up` and `restart-shell` warn when Omarchy's validator or the shell refuses it (`ls --json`: plugin_status). One the box has at its own path (in the repo `up` runs from, a same-path --ro-bind or an --overlay) is linked to there, as on a desk, so readlink -f leads into its repo; any other is mounted (plugin_status: via).

`plugin add PATH|ID` puts a plugin in a box that is up as --plugin would have: read-only, linked to where the box has it at its own path or mounted, made known to the shell (a rescan, until it lists it) and enabled, its state said (`ls --json`: plugin_status). `plugin remove ID` takes one out (one from up's --plugin too): disabled, unmounted or unlinked, rescanned. A link made by hand in the box HOME works only for a folder the box has at its own path, and `omarchy plugin enable` right after `rescanPlugins` says "is not known" until the rescan is done; `plugin add` does both. Not inside ai-jail, nor on a box a jail started (up --plugin there).

--desk-shell: your desktop's shell as it is, to check a plugin against a real desk: every plugin in ~/.config/omarchy/plugins (read-only, as --plugin's; a --plugin of the same id wins: your working copy) but omabox's own widget (it lists your boxes; --plugin mounts it), your shell.json unfiltered (only idle held off: a box has no real input; omabox's widget taken out of it), and the other files in ~/.config/omarchy your plugins read (a plugin's JSON, a folder beside shell.json) copied into the box's. Never api-keys.env nor anything named or holding a key, token, secret, password, credential, auth, cookie or session (any .env, .pem, .gpg...), hooks/ (your scripts), a git dir or a backup; regular files up to 1 MiB (16 MiB, 1000 in all); a link only to a file inside the folder. `up` says what went in and what did not, and why (`ls --json`: desk_shell). Not with --stock-bar or --stock; not inside ai-jail.

--hyprland PATH: the box runs that binary (its folder mounted read-only at its own path) with the box's aquamarine, so a build must link a libaquamarine soname the box has (checked before the box starts); hyprctl and hyprpm stay the installed ones (a warning when the versions differ). PATH may be a folder, mounted whole: an unpacked package (usr/bin/Hyprland, as `bsdtar -xf` leaves one, its libraries in usr/lib), an install prefix (bin/Hyprland, lib) or a build folder (Hyprland, hyprctl/hyprctl); its libraries come first (its aquamarine is the box's) and its hyprctl is the box's. OMABOX_HYPRLAND=PATH is the default for every `up` (a suite on another Hyprland). `ls` and `windows` name it. Compositor logic runs for real (layouts, focus, input routing, the Lua config, IPC, protocols); DRM/KMS, real monitors, HDR/VRR, multi-GPU, libinput with real devices and the session and suspend paths never run in a box (the lock screen does, without a real password). --quickshell PATH: the box's shell (and `quickshell`/`qs` on its PATH, and omabox's own calls to its shell) runs that binary, its folder mounted read-only at its own path. Quickshell uses Qt's private API, so the build must be one against the installed Qt: `up` refuses a build against another Qt, or one needing a library the box lacks, naming both. `ls` and `windows` name it; `ls --json` has quickshell_version (`quickshell --version` in the box, every box's), which is the last release's number, never proof that a fix is in: a build of an unreleased commit says it too.

`shot --no-pointer` (a screen shot, --burst too) and `record --no-pointer` leave the pointer out, for stills and videos meant for people (no arrow on the app, none parked on a hover state): it is hidden (Hyprland's cursor:invisible), a frame without it awaited (up to a second), and shown again after, as it was, also on a failure or Ctrl-C; a recording keeps it hidden until `record stop`. `pointer hide` (or `up --no-pointer`) hides it in the box until `pointer show`, over config reloads and theme switches (omarchy-theme-set reloads). Hidden, it still moves and clicks where it is told, focus still follows it, and peek's marks still show it; `wait` and `--changed` leave out where it is, as they do when it shows.

$OMABOX_READY_TIMEOUT: how long `up` waits for Hyprland and the shell (default 30s).

Interactive boxes and peek windows open on workspace 9, without focus: `omabox config workspace WS` (1-99; special:omabox, a special workspace of omabox's own: the bar widget's Show opens it, a workspace switch hides it; special:NAME; special = Omarchy's scratchpad on SUPER+S, on 4.5 its Quake console) or --workspace. A peek window shows click, pointer and keys for ~3 s (a ring, key captions, --pass values as *); never the box's own frames.

Closing an interactive box's window ends the box; `omabox config confirm-close on` asks first (a second close is a yes). A headless box renders on the first GPU; `omabox config gpu` lists them, and `omabox config gpu nvidia` (amd, intel, a driver's name, or a PCI slot: two GPUs of one kind) picks another; `up` falls back to the first, saying so and why, when that one is not there (a card handed to a VM). The first is one that renders: a VM's virtio-gpu without virgl (software only) comes after any other, and when it is the only one `up` refuses it before starting a box that would die there. $OMABOX_RENDER_NODE overrides it. An interactive box renders on the GPU your desktop's compositor uses, whatever the setting. `omabox config protect-ports 8080,5432` keeps those host ports from every connected box, through any of the host's addresses (an isolated box's --allow refuses them; `default` removes them; it needs nft). `omabox config desktop plain` (or omarchy) is the desktop of a box up gets without --desktop; auto, the default, is Omarchy's where Omarchy is installed and plain where it is not.

aquamarine's fix for nested Wayland outputs (hyprwm/aquamarine#415, until the system's has it: a release, or a package patched with it; omabox looks for what the fix added, not the version): a headless box on an NVIDIA render node and confirm-close need it, and `up` refuses them without it; `omabox setup --aquamarine` builds it (a checkout's build/prefix, else ~/.local/share/omabox), with omabox's own fixes for interactive boxes on top: a key held when the window loses focus is released, and in a monitor's window your pointer lands on that monitor and your cursor stays shown. No system aquamarine has those, so it builds even when the system's has the fix; it builds nothing only when boxes already use this omabox's build (--force rebuilds it). It builds the aquamarine the installed Hyprland links: 0.15.1 with the fix for Hyprland 0.56 (libaquamarine.so.14), 0.16.0 for Hyprland 0.57 (.so.15; there Hyprland itself puts the pointer on the right monitor). For a Hyprland that links another, it builds nothing, says so and exits 0: boxes use the system's. `omabox --version` says which one new boxes use: a private build, or the system's (with the fix, patched with it, or without it). A git worktree of omabox with no build of its own uses its main checkout's build/prefix, and says so. OMABOX_AQUAMARINE=system: the system's aquamarine all the same (testing).

SUPER + ALT + ESCAPE toggles sending SUPER keys to an interactive box, once: until focus leaves it, or a key is pressed with the pointer off it. `keys-to-box on` makes them follow focus and the pointer, for the box's lifetime: its window has focus and the pointer is over it, SUPER is the box's; focus goes elsewhere or the pointer leaves it (your bar, another monitor), it is yours, and the pointer back over it gives it to the box again. SUPER + ALT + ESCAPE over the box gives the keys back until the box loses focus and gets it again. No argument prints on or off. While keys go to a box, its window's border takes the theme's red and the bar widget's icon is lit.

--dnd, `dnd on`: the box's Do Not Disturb, in its own Omarchy shell (never your desktop's): new notifications stay off its screen, so no toast lands over a window's corner between steps (Omarchy still shows a critical notify-send, a verification code and its own action toasts, such as a layout change's). --dnd also dismisses any toast up when the box is ready; `dnd --clear` does that at any time. Bare `dnd` prints on or off. A box `--from` a save keeps the save's (Omarchy 4.5 keeps it in its notifications state). --no-dock, `dock off`: Omarchy 4.5's dock disabled in the box's shell (its shell.json's disabledPlugins, as `omarchy plugin disable omarchy.dock` writes it), its layer gone. The dock shows only on a floating workspace; elsewhere its layer stays mapped, taking no input. Bare `dock` says, per monitor, whether it is shown (its icons take input), tucked away (auto-hide or a maximised window: only the strip along its edge, until the pointer reaches it) or hidden (none); --json the same as an object. Both refuse a box with no shell; dock one whose Omarchy has none (before 4.5).

A headless box goes down after $OMABOX_IDLE (default 2h) with no omabox command against it, no peek window and no `omabox run` still running; --idle 30m|2h|0 (never) per box. Interactive: never. Write the unit: a bare --idle 45 is refused (minutes up to 0.9, seconds everywhere else).

A `run -d` job is not activity: a server only polled over HTTP needs --idle 0 (or longer). At --idle 0 a session's box still goes with its agent (`ls` says never); a box with another name (-b NAME) stays.

A headless box at --idle 0 with no agent to go with stays up until `down`. Once what started it is gone (the script or agent whose command ran `up`), `ls` says orphan under IDLE (`ls --json`: orphan) and `down --orphans` takes those down; nothing does by itself. One you started at a terminal, outside an agent session, is yours: never an orphan. A session's subagents share its id, so its default name. `ls` says under each box where it was started and by which agent session (and who used it last, when another; `ls --json`: dir, session). A `down` of a box another caller started or used in the last 10 minutes warns that it may be another agent's, and still takes it down; the name's next command says when a down took it, and from where.

Sizes: WxH is @60; `host` copies your focused monitor's size and refresh rate (scale stays 1). `,scale=S` (1 to 4, as a monitor's) gives the main screen a scale, headless only: `--size 3840x2160,scale=2` is a 4K screen laid out as 1920x1080, the bar and apps their usual size in twice the pixels, so a `shot` of it is 3840x2160 (coordinates stay the layout's: `click --in` maps a shot's). `mode WxH` without one is scale 1. Hyprland may round a scale to whole pixels (`mode` says so). Measure rendering cost with `omabox gpu` (and `omabox cpu`) in a box whose mode matches your monitor.

More monitors: `up --monitor SPEC` (repeatable) or `monitor add SPEC` on a running box. SPEC is WxH[@HZ][,scale=S][,right|below|X,Y]: placed right of the last one made by default, or below it, or at X,Y in the layout (which starts at 0,0 on the main screen: no left or above). Scale 1 to 4; Hyprland may round it to a whole-pixel size (2560x1440 at 1.5 becomes 1.6). The main screen (--size, `mode`) is HEADLESS-2; the others HEADLESS-3, -4, ... (or --name); on NVIDIA, where a box draws on Wayland outputs, WAYLAND-1 and WAYLAND-2, -3, ... (no --name); there a headless output a program makes itself (`hyprctl output create headless`) is listed 0x0, which `monitor list` and `shot` say, naming a box on another GPU to test it in. `monitor remove NAME` unplugs one: Hyprland moves its workspaces to the others. They survive a config reload, and one placed right or below moves when the one before it changes size (`mode`, said) or goes; an X,Y one stays. Coordinates (click, drag, pointer, pixel, -g) are the layout's (`pixel` refuses a point in a gap between them); `shot --monitor NAME` takes one monitor (a shot of a mixed-scale layout comes out at the highest scale: --fit). `peek` shows the main screen, `peek --monitor NAME` another: a window per monitor, tiled on the workspace, each marking the clicks and pointer on its own monitor (keys on all); one whose monitor drops (`output drop`) says it is gone, and shows it again once it is back; the whole layout at once is `shot`. An interactive box's monitors are windows on your desktop, on its workspace, placed in the box as a headless box's; on your screen the box's layout scaled as a whole, as display settings draw it: one scale for every window (at most 1), the picture centred on the monitor its main window is on, the main window floated for it (it tiles again when the last monitor goes); each `monitor add` and `remove` lays it out again. Each window is a view of its monitor: the monitor's size in the layout, which the bar and apps see, is the one asked for (the main screen's --size, a SPEC's), its mode its window's pixels at a scale of at most 1 (`monitor list`). Resizing a window changes its view's scale, not the monitor (a window of another shape shows it smaller along one side); closing one unplugs it. They need aquamarine's fix, as NVIDIA boxes do, and omabox's build of it puts your pointer on the monitor whose window it is in and keeps your cursor shown from one window to the next (`monitor add` says when a box's aquamarine does neither).

Crashes in a box skip the desktop's crash notifications (core limit 1 byte; raise it inside for a core).

A save keeps what a box's apps set up (signed in, a PIN, a library): the box HOME without .cache and its logs, keyring included, paused for the copy. `up --from` starts with it, then seeds your Omarchy look on top as for any box (theme, bar, terminals: today's, or --theme's, not the save's). Close an app first for a clean save. Saves live in ~/.local/share/omabox/saves until `saves rm`.

#### omabox down

End a box and everything in it. A session's box also goes when its agent exits.

Examples:

```
$ omabox down
$ omabox down --all
```

```
omabox down [NAME | -b NAME | --all | --orphans]       --orphans: the boxes ls calls orphans (no idle limit, starter gone)
```

`omabox help down` adds:

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

A headless box at --idle 0 with no agent to go with stays up until `down`. Once what started it is gone (the script or agent whose command ran `up`), `ls` says orphan under IDLE (`ls --json`: orphan) and `down --orphans` takes those down; nothing does by itself. One you started at a terminal, outside an agent session, is yours: never an orphan. A session's subagents share its id, so its default name. `ls` says under each box where it was started and by which agent session (and who used it last, when another; `ls --json`: dir, session). A `down` of a box another caller started or used in the last 10 minutes warns that it may be another agent's, and still takes it down; the name's next command says when a down took it, and from where.

#### omabox ls

Every box: its mode, size, state, whether its bar is running (and how often it crashed), network, idle time and plugins. `--json` adds what each one tested: the Omarchy version, the theme, each plugin's commit.

Examples:

```
$ omabox ls
$ omabox ls --json
```

```
omabox ls [--json]
```

`omabox help ls` adds:

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

A headless box at --idle 0 with no agent to go with stays up until `down`. Once what started it is gone (the script or agent whose command ran `up`), `ls` says orphan under IDLE (`ls --json`: orphan) and `down --orphans` takes those down; nothing does by itself. One you started at a terminal, outside an agent session, is yours: never an orphan. A session's subagents share its id, so its default name. `ls` says under each box where it was started and by which agent session (and who used it last, when another; `ls --json`: dir, session). A `down` of a box another caller started or used in the last 10 minutes warns that it may be another agent's, and still takes it down; the name's next command says when a down took it, and from where.

#### omabox path

Where a box lives on disk; its HOME is `<dir>/home`, so you can seed an app's data files there.

Examples:

```
$ omabox path
$ omabox path --logs
```

```
omabox path [NAME | -b NAME] [--home | --run | --logs [--json]]   the box dir; --home: its HOME (<dir>/home);
                                                       --run: its /run/user/$UID (<dir>/run); --logs: each log's file
```

`omabox help path` adds:

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

From the host, the box's HOME (/home/sbx in it, or your HOME's path in a desk box) is <dir>/home, `omabox path --home`, and its /run/user/$UID (its XDG_RUNTIME_DIR: sockets, an app's runtime state) is <dir>/run, `omabox path --run`. An agent reads and writes box files with its own file tools on the path --home prints. The host's own /run/user/$UID is the real session's: never read a box app's state there.

#### omabox mode

Show or change a headless box's screen size and refresh rate while it runs.

Examples:

```
$ omabox mode 3440x1440@144
```

```
omabox mode [-b NAME] [--json | WxH[@HZ][,scale=S]|host]   show or change a headless box's screen mode
```

`omabox help mode` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Sizes: WxH is @60; `host` copies your focused monitor's size and refresh rate (scale stays 1). `,scale=S` (1 to 4, as a monitor's) gives the main screen a scale, headless only: `--size 3840x2160,scale=2` is a 4K screen laid out as 1920x1080, the bar and apps their usual size in twice the pixels, so a `shot` of it is 3840x2160 (coordinates stay the layout's: `click --in` maps a shot's). `mode WxH` without one is scale 1. Hyprland may round a scale to whole pixels (`mode` says so). Measure rendering cost with `omabox gpu` (and `omabox cpu`) in a box whose mode matches your monitor.

#### omabox monitor

Add, remove and list a headless box's monitors while it runs: any size, scale and place, a bar on each. `remove` is an unplug: its workspaces move to the others.

Examples:

```
$ omabox monitor add 3440x1440,0,1080
$ omabox monitor list
$ omabox monitor remove HEADLESS-3
```

```
omabox monitor [-b NAME] (add SPEC [--name N] | remove NAME | list [--json])   a box's other monitors
```

`omabox help monitor` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

More monitors: `up --monitor SPEC` (repeatable) or `monitor add SPEC` on a running box. SPEC is WxH[@HZ][,scale=S][,right|below|X,Y]: placed right of the last one made by default, or below it, or at X,Y in the layout (which starts at 0,0 on the main screen: no left or above). Scale 1 to 4; Hyprland may round it to a whole-pixel size (2560x1440 at 1.5 becomes 1.6). The main screen (--size, `mode`) is HEADLESS-2; the others HEADLESS-3, -4, ... (or --name); on NVIDIA, where a box draws on Wayland outputs, WAYLAND-1 and WAYLAND-2, -3, ... (no --name); there a headless output a program makes itself (`hyprctl output create headless`) is listed 0x0, which `monitor list` and `shot` say, naming a box on another GPU to test it in. `monitor remove NAME` unplugs one: Hyprland moves its workspaces to the others. They survive a config reload, and one placed right or below moves when the one before it changes size (`mode`, said) or goes; an X,Y one stays. Coordinates (click, drag, pointer, pixel, -g) are the layout's (`pixel` refuses a point in a gap between them); `shot --monitor NAME` takes one monitor (a shot of a mixed-scale layout comes out at the highest scale: --fit). `peek` shows the main screen, `peek --monitor NAME` another: a window per monitor, tiled on the workspace, each marking the clicks and pointer on its own monitor (keys on all); one whose monitor drops (`output drop`) says it is gone, and shows it again once it is back; the whole layout at once is `shot`. An interactive box's monitors are windows on your desktop, on its workspace, placed in the box as a headless box's; on your screen the box's layout scaled as a whole, as display settings draw it: one scale for every window (at most 1), the picture centred on the monitor its main window is on, the main window floated for it (it tiles again when the last monitor goes); each `monitor add` and `remove` lays it out again. Each window is a view of its monitor: the monitor's size in the layout, which the bar and apps see, is the one asked for (the main screen's --size, a SPEC's), its mode its window's pixels at a scale of at most 1 (`monitor list`). Resizing a window changes its view's scale, not the monitor (a window of another shape shows it smaller along one side); closing one unplugs it. They need aquamarine's fix, as NVIDIA boxes do, and omabox's build of it puts your pointer on the monitor whose window it is in and keeps your cursor shown from one window to the next (`monitor add` says when a box's aquamarine does neither).

#### omabox output

A screen goes and comes back under its own name, as a monitor that drops off on wake does, so you see what your shell and apps do then. `--cycles` stops at the first shell crash.

Examples:

```
$ omabox output drop --for 300ms
$ omabox output drop HEADLESS-3 --cycles 20
```

```
omabox output [-b NAME] (drop [OUT] [--for DURATION] [--cycles N] | back [OUT])   a screen gone (a monitor off), and back
```

`omabox help output` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`output drop [OUT]` removes one of a headless box's screens, as a monitor that drops off on wake (standby, a KVM, a dock) does: the shell and apps lose their per-screen windows and rebuild them on its return. Without OUT the main screen (`mode`'s; other monitors stay on, and while it is away `mode` says so); OUT is a monitor's name (`monitor list`, which lists the dropped ones too). Both, one after the other, leave the box with no screen. Dropping one twice is refused. `output back [OUT]` brings OUT back, without it every one dropped, each with the same name, mode, position and scale (a monitor's place is kept while it is away: a config reload does not bring it back, and the others stay where they are). --for DURATION does both, the screen gone that long; --cycles N repeats, with gaps from 50ms to 2s without --for (a second after each return), and stops at the first shell crash (exit 1, its report named). Not in an interactive box (its screens are its windows on your desktop: one dropped could not come back).

#### omabox reload

A box keeps the Hyprland config it started with, so updating omabox never resets a running test. `reload` gives it this omabox's config.

Examples:

```
$ omabox reload
```

```
omabox reload [-b NAME]                                the box's Hyprland config again, from this omabox
```

`omabox help reload` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--autoreload: the box's Hyprland reloads its config when a file it loaded changes, as a desktop's does; a box turns that off, so an update of omabox or Omarchy leaves it as it is. For a project that must see what a file change does (a helper rewriting a file the config loads, on a Hyprland event, reloads for ever). Its config is still the box's own copy; an Omarchy update reloads it too.

A box's Hyprland runs a copy of omabox's config made at `up`, with autoreload off (unless `up --autoreload`): updating omabox (a pull, an upgrade) leaves running boxes' config as it is (its other scripts in a box are the new ones from their next start: shell.sh at `restart-shell`). `reload` copies this omabox's config in (only when it differs) and reloads it; like any config reload, binds, rules and Lua state added since are gone.

#### omabox save

Keep a box's HOME (an app signed in, a PIN, a library) so new boxes start from it.

Examples:

```
$ omabox save signed-in
$ omabox up --from signed-in
```

```
omabox save SAVE [-b NAME] [--force]                   keep the box's HOME: up/run --from SAVE start from it
```

`omabox help save` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

A save keeps what a box's apps set up (signed in, a PIN, a library): the box HOME without .cache and its logs, keyring included, paused for the copy. `up --from` starts with it, then seeds your Omarchy look on top as for any box (theme, bar, terminals: today's, or --theme's, not the save's). Close an app first for a clean save. Saves live in ~/.local/share/omabox/saves until `saves rm`.

#### omabox saves

List the saves, or delete them.

Examples:

```
$ omabox saves
$ omabox saves rm signed-in
```

```
omabox saves [--json] | saves rm SAVE...               the saves: list, delete
```

`omabox help saves` adds:

A save keeps what a box's apps set up (signed in, a PIN, a library): the box HOME without .cache and its logs, keyring included, paused for the copy. `up --from` starts with it, then seeds your Omarchy look on top as for any box (theme, bar, terminals: today's, or --theme's, not the save's). Close an app first for a clean save. Saves live in ~/.local/share/omabox/saves until `saves rm`.

### Run, look and wait

#### omabox run

Run any command inside a box. `-d` launches an app and returns; `--replace` restarts it after a rebuild. With no box up, a throwaway box runs the command and goes.

Examples:

```
$ omabox run -d --wait -- ./build/app
$ omabox run -d --replace --wait -- ./build/app
$ omabox run -- ctest --test-dir build
```

```
omabox run [-b NAME] [-d [--wait] [--replace] [-q] [--print-log]] [--pass VAR]... [--env-file FILE]...
           [UP OPTIONS] -- CMD [ARG...]                UP OPTIONS: up's, for a throwaway box only
```

`omabox help run` adds:

```
omabox up [NAME] [--size WxH[@HZ][,scale=S]|host] [--interactive] [--plugin PATH|ID]... [--overlay DIR]...
          [--ro-bind DIR[:DEST]]... [--seed SRC:DEST]... [--net isolated [--allow PORT,...] [--addr ADDR]...|host]
          [--env KEY=VAL]...
          [--no-seed extensions,fonts]                 your plugins' settings files, your fonts left on the desk
          [--theme-dir DIR]...                         a theme you are editing, live, in the box's themes/
          [--theme NAME]                               start on that theme, not your desktop's current one
          [--monitor WxH[@HZ][,scale=S][,right|below|X,Y]]...     more monitors
          [--idle DURATION] [--stock-bar] [--systemd] [--xwayland] [--autoreload] [--no-shell] [--from SAVE]
          [--desk-shell]                               your desktop's whole shell: every plugin, shell.json, their files
          [--audio] [--polkit]                         its own PipeWire (a silent mic); a polkit agent can register (polkit ask)
          [--no-pointer] [--dnd] [--no-dock]           no pointer (pointer show); Do Not Disturb on; 4.5's dock off
          [--stock | --clean [--keep animations,bar,clock,fonts,identity,locale,pointer,wallpaper]]   a new user's look; --clean: frozen too
          [--hyprland PATH]                            a Hyprland build or folder of yours, not the installed one
          [--quickshell PATH]                          a Quickshell build of yours for the box's shell
          [--omarchy DIR | --desktop plain|desk [--shell CMD]]   an Omarchy tree (a checkout); plain: nothing of Omarchy's, CMD its shell; desk: plain at your HOME's path
          [--workspace WS] [--confirm-close | --no-confirm-close]      (interactive)
          [--new]                                      start it under a free name, box-1, box-2, ... (printed)
          [--json]                                     the box as ls --json lists it, on stdout
```

NAME defaults to $OMABOX, else the current git repo's name, else "default". In an agent session (Claude Code, Codex, `guard exec`) that name gets the session's id, myrepo-5cc72cdc: one box per session, gone when its agent exits. OMABOX_SESSION= (empty) turns that off. A git worktree is named by its own folder, so each worktree has its own box. Outside any repo (a scratch dir) the name is default-SESSION; with no box of that name, every command but `up` uses the session's one box started from its repo, said once: `down` too, so `omabox down` there takes that box down. A `down` whose name has no box, while the session has boxes up started elsewhere, names each with the `down -b` that takes it, and exits 1.

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--strict] [--json]        [--expect tree TEXT] [--tree] (not run's)        after it, a change on screen within --start, then still for --quiet; 124 if not by --timeout;        the line adds what changed on the desktop (windows, layers, focus), a 124 where the input went

-d (or --detach): the command left running in the box, its pid on stdout (J=$(omabox run -d -- APP)), pid and log said on stderr; --replace: the same one stopped first

`omabox run` with no box up starts a throwaway box for the command, with the current repo mounted as a discarded overlay (writes succeed, vanish at teardown), and tears it down after. A box named with -b or $OMABOX must be up: `run` fails rather than start a throwaway. With a box up, `run` uses it and the repo is read-only there (tests that write into the tree: down first). Outside any repo a throwaway mounts nothing of the current dir: the command runs in the box HOME (/home/sbx), said when a word of it is a path there; `run --overlay DIR` (or --ro-bind DIR) brings it in. --net isolated --allow PORTS on a throwaway `run` keeps tests off your real local services. `run` exits with the command's status; 125 is run's own failure (no box, a bad option, a throwaway that did not start, the box going down while the command ran), never a code of the command's (omabox help exit-codes).

Every box has its own network (pasta): by default the internet, the LAN and your servers. Across the box boundary use 127.0.0.1, not localhost; a box's servers appear on your 127.0.0.1 about a second after they listen, one box per port (a box server on a port the host or another box has fails to start, address in use; of two started within a second, only one gets it there: `omabox ports` names the holders). --net isolated: a loopback and the --allow ports only, which are for reaching those host ports from the box: pasta listens on each in the box, so a box server on one fails, address in use (`ports`: allowed); serve on another; --addr ADDR (repeatable) puts an address on that loopback, for an app that wants a peer from a non-local address: one in a documentation range (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32). A server on 203.0.113.10 sees a client bound to 203.0.113.11 come from there. --net host (asked for by name only; no config picks it): your host's network itself, no pasta, for a tool that scans the real LAN. The box keeps its own seat, session bus, runtime dir and HOME, but its servers take your host's real ports (they collide with your services and other host boxes; nothing is forwarded, `ports`: host-net), it sees your real interfaces and its ARP and ICMP reach your LAN. Not for code you do not trust. Refused with --allow, --addr, --xwayland (its X server would be your host's), --desktop desk, inside ai-jail, and while protect-ports names a port.

`run` starts the command with the box's environment, not yours: --pass VAR hands it one of your variables (a password too: never on a command line); --env-file FILE hands it a file's KEY=VAL lines (a dev.env: read as data, nothing expanded; --pass wins); `keys --pass VAR` types one (never `-t` for a secret: the process list shows it). `keys -t` and `keys --pass` type newline and tab (Return, Tab); any other control character is refused (exit 2); a value's one trailing \r is dropped. --env KEY=VAL is the box session's, on `up` (and a throwaway `run`'s box); `run --env` on a box that is up hands it to the command, as --env-file does (--pass wins). Never what the session sets itself (PATH, HOME, XDG_RUNTIME_DIR, XDG_*_HOME, WAYLAND_DISPLAY, DISPLAY, HYPRLAND_INSTANCE_SIGNATURE, LD_PRELOAD, OMABOX_BOX...), by any of them.

--seed SRC:DEST: a file or folder of yours copied into the box HOME at DEST (.config/x or ~/.config/x) before its session starts, for a plugin that reads its config once at start; the same refusals as --ro-bind (no secret stores; nothing in ~/.config/omarchy but plugins/ and themes/). A copy: the box's changes stay in the box; a link already in DEST is replaced, never written through. Never into a --plugin's or --theme-dir's folder there (refused: it would replace the plugin or theme): write the file in that folder instead.

--no-seed extensions: the box starts without your ~/.config/omarchy/extensions (the plugins' settings files, the menu's extension), with a new Omarchy user's (/etc/skel's; a --from save's own stay). Otherwise `up` copies it, and says each file a --plugin's code names there ("seeded extensions/NAME.json from your desk"): that plugin starts on your desk's settings, an on/off switch in them too. --no-seed fonts: the box starts without your fonts. Otherwise ~/.local/share/fonts and ~/.fonts are mounted read-only at the same place in the box HOME (`ls --json`: desk_fonts), so a theme's or a plugin's own faces draw as on your desk (not in a --stock box, nor a --clean one unless --keep fonts; nor when the box HOME has its own folder there, a --from save's or a --seed's: it keeps that one). A link in them that leads out of them is not in the box (said). Comma-separated, repeatable.

--theme-dir DIR: a theme you are editing, live: the box HOME's ~/.config/omarchy/themes/NAME (DIR's name) is a link to DIR at its own path, in place of the copy `up` makes of each of your themes. The box has DIR there when it is in the repo you run from, a same-path --ro-bind or an --overlay; any other DIR is mounted read-only there, refused as --ro-bind's are. omarchy-theme-set NAME in the box applies it, as it is then.

--theme NAME: the box starts on that theme (Omarchy's, one of yours or a --theme-dir one; checked before anything is made), not your desktop's current one: omarchy-theme-set NAME runs in the box before its Hyprland and bar start, so a test gets the same look whatever your desktop is on (its background: your own first for NAME, else the theme's; with --stock the theme's). Over a --from save's look too. `up` again with another is refused.

--stock-bar: Omarchy's default bar (its shell.json, no shell.toml), not a copy of yours: for shots, sizes and colours as most people see them. --theme leaves your bar as it is; without this `up` says when that bar is not Omarchy's ("seeded the bar from your desk: its shell.json layout and shell.toml [bar]"). Plugins are placed as without it. --stock: the rest of a new user's desktop too.

--no-shell: Hyprland only, no Omarchy shell (faster; no bar, tray or notifications). --desktop plain (#247): the box's Hyprland runs omabox's own small config (Hyprland's defaults, your   keyboard layout from /etc/vconsole.conf, SUPER+RETURN a terminal, SUPER+W closes) and sees an empty   /usr/share/omarchy, as on a machine without Omarchy: no shell but --shell's, and a HOME with none of   your Omarchy look (git's name and email only). --plugin, --theme, --theme-dir, --stock-bar, --stock,   --desk-shell, --omarchy, --dnd and --no-dock need Omarchy and are refused, as are the dnd, dock and   plugin commands on the box. Without --desktop: `omabox config desktop`'s, else omarchy where Omarchy   is installed and plain where it is not (up says so; doctor and setup test the same); --omarchy DIR   is an Omarchy box. ls says a plain box's desktop (and shell) under its line. --desktop desk (#321): your own desktop in a box, its HOME at your HOME's path ($HOME in the box is   yours), so what names your paths finds the box's: still the fake HOME, never your files (but the   repo, --ro-bind, --seed's and the copy of your desktop). From the host it is <dir>/home, as any   box's; a path under your HOME in a command is the box HOME's there, not yours (run says so). A   mount (--ro-bind, --overlay) goes inside that HOME, never at it or above it, over omabox's own   files in it, nor through a link in it. up copies in your ~/.config/hypr (links followed, as   copies), the config and state of the shell it finds, and the images they name, before --seed's;   never a secret store or what looks like a key, capped, what it left out said (box.json desk_copy).   It needs a Lua config (a hyprland.conf alone is refused: hyprctl eval refuses it). Its base is your   desk's: Omarchy's (Omarchy here and your hypr/hyprland.lua loading it: an Omarchy box, its shell   Omarchy's with your plugins and shell.json, as --desk-shell copies them; it takes --plugin,   --theme, --theme-dir, --dnd, --no-dock and --omarchy, refuses --stock, --stock-bar and --keep),   else plain. Its Hyprland runs your copied hyprland.lua; what it starts goes through an autostart   policy (idle and lock daemons, your systemd session, system-bus applets, what the box runs itself   are dropped; binds run as on your desk), each decision a line of `omabox log autostart`. Its idle is   held off (tools/idlehold): your shell's idle timeouts never lock or blank it. On a plain base its   shell is the one your config starts (DMS, Noctalia, Caelestia, Waybar, a Quickshell config), run in   the box's shell slot as --shell's: up waits for it and says which, and ls, pid shell, log shell and   restart-shell work on it; a second shell your config starts is dropped. --shell CMD runs another in   its place, --no-shell none; a config that starts none omabox knows fails up, saying so. Refused   with --desk-shell (part of it; alone it still works, with a note), --clean (the path carries your   login name) and inside ai-jail (not yet); `omabox config desktop` does not take desk yet, and   `check run --desktop desk` is refused (a check needs the same box every run). --shell CMD (#247, plain only): the box's shell is CMD (`dms run`, `qs -p DIR`, `caelestia shell   -d`), run by sh in the session; the shell is all CMD starts (#438): a launcher may start it and   exit, and the shell is gone once nothing of it is left. up waits until one of its processes draws   a layer (OMABOX_READY_TIMEOUT), says when it exits or crashes on the way; log shell is its output,   restart-shell stops all of it and starts CMD again, a Quickshell crash of its config is the   shell's. An app the shell starts itself counts as the shell (not one through `hyprctl dispatch   exec`). --quickshell PATH: the build is CMD's `qs` and `quickshell` (on the session's PATH).

--stock: Omarchy as a new user sees it, for a showcase or a shot for someone else: Omarchy's bar (--stock-bar) on tokyo-night (or --theme) with the theme's own wallpaper (never yours for it), English (en_US.UTF-8, else C.UTF-8) in UTC for the whole session, and nothing of your desk's look: not your terminal configs and terminal choice, branding, themes (but the one --theme names, when it is yours and not Omarchy's), wallpapers, plugins' settings (as --no-seed extensions), Hyprland toggles or fonts; a new user's HOME (/etc/skel's) instead. The clock, pointer, network and animations are as in any box; --plugin, --theme-dir and the rest work on top (`ls --json`: stock, a clean box's too). Your git name and email stay (git config --global user.name and user.email, so a commit in the box works): a shot of a git log shows them. Over a --from save, the save's HOME stays as saved (said); the bar, theme and locale are stock. Not with --desk-shell.

--clean: --stock plus the run-to-run freezes, a desktop where only what is tested moves, for shots compared across runs (`check`): a #ff00ff wallpaper (no theme has it: any of it inside a window or the bar is a hole), the bar's clock frozen at "Friday 12:00" (in its place, at its width), no pointer, no network (--net connected gives it back), animations off (over reloads too), and no name of yours: the user is `user` (no full name) and the host `omabox`. --keep LIST takes any of animations, bar (yours), clock, fonts (yours), identity (your user and host names), locale (yours and your timezone), pointer, wallpaper (the theme's) back. A theme set later in the box brings that theme's wallpaper. On a plain box: no bar, theme or clock (--keep bar and clock refused), and the sentinel is its Hyprland's background colour (misc:background_color), not a wallpaper.

--audio: the box's own PipeWire, WirePlumber and pipewire-pulse (PipeWire and Pulse apps both play), its only devices a speaker nobody hears (omabox-speaker, a null sink: the default output) and a silent microphone (omabox-mic, the default input). Nothing reaches your audio: a box has no /dev/snd and its own runtime dir (its sockets, never yours). `audio` says whether the box made a sound, `record --audio` puts it in the video (AAC). Logs: `log audio`. Without it a box has no audio.

--polkit: a polkit agent in the box (the shell's polkit plugin, a copy of it under test, a GTK or Qt agent) registers and is asked, as on a desktop, and the end of each request is the agent's own. A box has no system bus and no logind session, and never gets yours: it gets a system bus of its own where only polkit's name can be owned, by a stand-in authority, which keeps the agents as polkitd does (one per session, dropped when they leave the bus) and makes a request only when `polkit ask` does. In place of PAM it answers polkit's agent helper with a password prompt, and takes the one password `ask --accept` names (a test's, never yours). It decides nothing for any service: pkexec, pkcheck and mechanisms get no answer from it. The bus is the box's (its processes share one uid, so one can answer in the stand-in's place): what `polkit` prints of it is bounded and plain. The box's processes are in a session named "omabox" (XDG_SESSION_ID). Logs: `log polkit`.

--autoreload: the box's Hyprland reloads its config when a file it loaded changes, as a desktop's does; a box turns that off, so an update of omabox or Omarchy leaves it as it is. For a project that must see what a file change does (a helper rewriting a file the config loads, on a Hyprland event, reloads for ever). Its config is still the box's own copy; an Omarchy update reloads it too.

--plugin PATH|ID: a shell plugin, read-only, enabled where its manifest says; `up` and `restart-shell` warn when Omarchy's validator or the shell refuses it (`ls --json`: plugin_status). One the box has at its own path (in the repo `up` runs from, a same-path --ro-bind or an --overlay) is linked to there, as on a desk, so readlink -f leads into its repo; any other is mounted (plugin_status: via).

`plugin add PATH|ID` puts a plugin in a box that is up as --plugin would have: read-only, linked to where the box has it at its own path or mounted, made known to the shell (a rescan, until it lists it) and enabled, its state said (`ls --json`: plugin_status). `plugin remove ID` takes one out (one from up's --plugin too): disabled, unmounted or unlinked, rescanned. A link made by hand in the box HOME works only for a folder the box has at its own path, and `omarchy plugin enable` right after `rescanPlugins` says "is not known" until the rescan is done; `plugin add` does both. Not inside ai-jail, nor on a box a jail started (up --plugin there).

--desk-shell: your desktop's shell as it is, to check a plugin against a real desk: every plugin in ~/.config/omarchy/plugins (read-only, as --plugin's; a --plugin of the same id wins: your working copy) but omabox's own widget (it lists your boxes; --plugin mounts it), your shell.json unfiltered (only idle held off: a box has no real input; omabox's widget taken out of it), and the other files in ~/.config/omarchy your plugins read (a plugin's JSON, a folder beside shell.json) copied into the box's. Never api-keys.env nor anything named or holding a key, token, secret, password, credential, auth, cookie or session (any .env, .pem, .gpg...), hooks/ (your scripts), a git dir or a backup; regular files up to 1 MiB (16 MiB, 1000 in all); a link only to a file inside the folder. `up` says what went in and what did not, and why (`ls --json`: desk_shell). Not with --stock-bar or --stock; not inside ai-jail.

--hyprland PATH: the box runs that binary (its folder mounted read-only at its own path) with the box's aquamarine, so a build must link a libaquamarine soname the box has (checked before the box starts); hyprctl and hyprpm stay the installed ones (a warning when the versions differ). PATH may be a folder, mounted whole: an unpacked package (usr/bin/Hyprland, as `bsdtar -xf` leaves one, its libraries in usr/lib), an install prefix (bin/Hyprland, lib) or a build folder (Hyprland, hyprctl/hyprctl); its libraries come first (its aquamarine is the box's) and its hyprctl is the box's. OMABOX_HYPRLAND=PATH is the default for every `up` (a suite on another Hyprland). `ls` and `windows` name it. Compositor logic runs for real (layouts, focus, input routing, the Lua config, IPC, protocols); DRM/KMS, real monitors, HDR/VRR, multi-GPU, libinput with real devices and the session and suspend paths never run in a box (the lock screen does, without a real password). --quickshell PATH: the box's shell (and `quickshell`/`qs` on its PATH, and omabox's own calls to its shell) runs that binary, its folder mounted read-only at its own path. Quickshell uses Qt's private API, so the build must be one against the installed Qt: `up` refuses a build against another Qt, or one needing a library the box lacks, naming both. `ls` and `windows` name it; `ls --json` has quickshell_version (`quickshell --version` in the box, every box's), which is the last release's number, never proof that a fix is in: a build of an unreleased commit says it too.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

$OMABOX_READY_TIMEOUT: how long `up` waits for Hyprland and the shell (default 30s).

--dnd, `dnd on`: the box's Do Not Disturb, in its own Omarchy shell (never your desktop's): new notifications stay off its screen, so no toast lands over a window's corner between steps (Omarchy still shows a critical notify-send, a verification code and its own action toasts, such as a layout change's). --dnd also dismisses any toast up when the box is ready; `dnd --clear` does that at any time. Bare `dnd` prints on or off. A box `--from` a save keeps the save's (Omarchy 4.5 keeps it in its notifications state). --no-dock, `dock off`: Omarchy 4.5's dock disabled in the box's shell (its shell.json's disabledPlugins, as `omarchy plugin disable omarchy.dock` writes it), its layer gone. The dock shows only on a floating workspace; elsewhere its layer stays mapped, taking no input. Bare `dock` says, per monitor, whether it is shown (its icons take input), tucked away (auto-hide or a maximised window: only the strip along its edge, until the pointer reaches it) or hidden (none); --json the same as an object. Both refuse a box with no shell; dock one whose Omarchy has none (before 4.5).

A headless box goes down after $OMABOX_IDLE (default 2h) with no omabox command against it, no peek window and no `omabox run` still running; --idle 30m|2h|0 (never) per box. Interactive: never. Write the unit: a bare --idle 45 is refused (minutes up to 0.9, seconds everywhere else).

`jobs` lists the box's `run -d` jobs still running, oldest first: PID (the job's command's, in the box, as `windows` shows its windows'), AGE, PROCS (processes of its session), LOG (its log, from the host) and COMMAND; --json: [{pid, age (seconds), processes, log, argv}]. A job that ended is not listed (its end, when early, is said by the next command). `stop JOB...` stops each job as `run -d --replace` stops one: SIGTERM to its session (what it forked included), SIGKILL after 5 s, then until its windows are gone (3 s), each said with how long it took. JOB is a job's pid, or the pid of any process of its session (a window's PID from `windows`); --all: every job. Its signals go through a pidfd of each process, checked to be the box's, never a pid number on the host. A stopped job's end is not said as a warning. Another process of the box: `omabox run -- kill PID`. Not a `run -d` job's pid: exit 1, nothing stopped.

`run -d` (or --detach) prints the job's pid alone on stdout, -q too (--print-log: the log's path instead; --wait --json: its "job"), first, before --wait's line: `J=$(omabox run -d -- APP)`, then `log run "$J"`, `wait log "$J" RE`, `wait job "$J"`, `stop "$J"`. None when nothing started (the error said, not 0). On stderr it says the job's pid and where its output goes (its log): -q says nothing (errors still). `run -d --replace` first stops what `run -d` started in that box with the same command and arguments (SIGTERM to its session, SIGKILL after 5 s) and waits for its windows to go: a rebuilt app in one step. Nothing else in the box is touched: an app started some other way stays, and so does a job of the same program with other arguments: named, with its pid and the `omabox stop PID` that stops it, and the new job starts beside it. A `run -d` whose command ends in its first 0.3 s, leaving nothing running (a server on a port already taken), says so instead of started, with its exit status and its log's last lines, and exits with that status. A `run -d --wait` whose command ended before the screen settled, leaving nothing running, says so too, and exits with that status (124 when it was 0: the screen is still the question); one killed or failed by the time the screen settled on something else (a window closing) is unsatisfied, said the same way. A job that ends later, within its first 30 s, with a status other than 0 (a server that dies a second in) is said once by the box's next command, whatever it is: "warning: run -d job CMD (pid N) exited with status 1 after 2.1s, since the last command (omabox log -b NAME run)". Not one --replace stopped, one killed (SIGTERM, SIGINT, SIGKILL) while an `omabox run` ran in the box or just after (`omabox run -- pkill APP`), nor one already said. A `wait window` or `wait layer` that gives up says such a job itself. When the job's log holds libwayland's line for a protocol error (the compositor closed its connection), each of these adds it: "its Wayland connection was closed for a protocol error: LINE". A GTK or Qt app's own line instead is said as a protocol error only when it says so, else as "its Wayland connection was lost: LINE" or "... failed: LINE".

A `run -d` job is not activity: a server only polled over HTTP needs --idle 0 (or longer). At --idle 0 a session's box still goes with its agent (`ls` says never); a box with another name (-b NAME) stays.

Sizes: WxH is @60; `host` copies your focused monitor's size and refresh rate (scale stays 1). `,scale=S` (1 to 4, as a monitor's) gives the main screen a scale, headless only: `--size 3840x2160,scale=2` is a 4K screen laid out as 1920x1080, the bar and apps their usual size in twice the pixels, so a `shot` of it is 3840x2160 (coordinates stay the layout's: `click --in` maps a shot's). `mode WxH` without one is scale 1. Hyprland may round a scale to whole pixels (`mode` says so). Measure rendering cost with `omabox gpu` (and `omabox cpu`) in a box whose mode matches your monitor.

Crashes in a box skip the desktop's crash notifications (core limit 1 byte; raise it inside for a core).

A save keeps what a box's apps set up (signed in, a PIN, a library): the box HOME without .cache and its logs, keyring included, paused for the copy. `up --from` starts with it, then seeds your Omarchy look on top as for any box (theme, bar, terminals: today's, or --theme's, not the save's). Close an app first for a clean save. Saves live in ~/.local/share/omabox/saves until `saves rm`.

#### omabox shot

A PNG of the screen, a region, one monitor, or one window's own pixels, even covered or on another workspace. `--changed` sends only what changed since the last shot, `--burst` a transition in frames.

Examples:

```
$ omabox shot
$ omabox shot --window myapp --fit 1280
$ omabox shot --changed --window myapp
$ omabox shot --burst 12 --sheet --after -- keys super+space
```

```
omabox shot [-b NAME] [-o FILE | FILE] [--window SEL | --active] [-g "X,Y WxH"] [--fit N | --zoom N] [--no-pointer] [--json]
            [--changed [--since SHOT] [--ignore "X,Y WxH"]...]    only what changed since the last shot of it
            [--grid N [--cell C3]]                  lettered cells to aim with, no tree; --cell: that cell, closer
            [--burst N [--every DURATION] [--diff] [--sheet] [-o DIR] [--after -- ACTION...]]   frames over time
```

`omabox help shot` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-o (or --output) names what the command writes.

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--monitor NAME: one monitor of the box's (omabox monitor list)

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

--fit N scales a shot's image down to N pixels on its longest side (a scaled screen's image is its layout times the scale: 2560 px for a 1280 px layout at 2). --zoom N (2-16, with -g) shows each pixel of a small crop as N x N, unblended: a 1 px border, a glyph's edge; `click --in` maps it back. -g "X,Y WxH" (or X,Y,W,H) crops: the screen's, or with --window the window's own coordinates; a region past the edge is cut to it, said on stderr (one with nothing inside is refused). At a fractional scale the image is the screen's own pixels from the one its start rounds to (30 at 1.25 is 37.5 px: from 38), not grim's blend, so find --image finds a crop where it was cut; the region recorded (stderr, --json, click --in) is the one asked. A cropped or scaled shot says so on stderr: `click --in SHOT X Y` (and `drag`, `pointer --in`) take that image's pixels (a window shot follows the window if it moved). Screen shots show the pointer (--no-pointer: not this one; `pointer hide`: none until `pointer show`); window shots never do. -o makes the file's folder if it is missing. An action `--in` a screen shot (click, scroll, drag, pointer) is refused, exit 1, when what is at its point is not what was there at the shot: another window or layer over it, or the window moved under it ("the screen changed at X,Y since SHOT: then on ..., now on ...; take a new shot"). A change elsewhere on the screen (a toast, a clock, a window away from the point) is not. One Hyprland read per point; a --burst frame is not checked.

`shot --grid N` (2-26) draws N lettered columns (A, B, ...) and N numbered rows over the shot (of the screen, -g, --monitor or a window), the labels in a 28 px margin top and left so nothing is hidden; stderr names each column's and row's span in the shot's coordinates. For a small target with no tree: `--grid N --cell C3` is that cell cropped as -g would, enlarged (--zoom, to about shot-fit's size, 1000 px without; --fit N or --zoom N to choose) and gridded again, its stderr saying the -g for a closer look still; a target a grid line cuts is both cells, `--cell C3:D3` (any rectangle of cells). `click --in GRID.png --cell C3` clicks the cell's middle; `click --in GRID.png X Y` takes the image's pixels, margin included (a point in it is refused). A grid shot is never what --changed compares with, nor a --since (shot --changed, wait change). Needs ImageMagick's magick.

`omabox config shot-fit N` makes --fit N every shot's default ($OMABOX_SHOT_FIT overrides it; off or `default` clears it): for a model that reads points in the smaller image its API scales a big one down to (1456 for 16:9 on Claude), set once. It goes wherever --fit goes (a window, -g, --monitor, --burst, drag --shot), not --changed or --zoom; --fit N wins, --fit 0 is full size.

`shot` writes PNG, whatever FILE is called: a name like x.ppm or x.jpg gets a PNG and a note on stderr (`magick x.png x.ppm` converts one).

`shot --burst N` takes N frames (2-200) of the same capture 100 ms apart (--every DURATION; --every 0: back to back, ~15 ms a crop, ~25 a 1920x1080 screen) into a folder, one line each: its path and time, with --diff where it differs from the frame before ("changed X,Y WxH", in the screen's coordinates as wait says them, whatever -g, --monitor or --fit took; with --window in the window's own, as `click --window` takes them). The whole burst is one capture client in the box, so Hyprland posts its screencast events once (four a monitor), not four a frame, which stalled the timers and animations of a shell or widget that works on each event: any pace is safe. Frames identical to the one before are counted on stderr: nothing new drawn between them. (A box started by an omabox from before takes a grim a frame, and says so: there, faster than 100 ms can stall them.) -o DIR: a folder used before loses the frame-NNN.png and sheet.png a burst left there, nothing else; without -o, a new folder each time. --after -- ACTION takes the first frame, then runs `omabox ACTION` (keys, click, scroll, run -d, monitor add ...) beside the rest: a transition from its start (a run there takes no --env-file: it reads no host file, as the skill pre-approves shot). --sheet adds one contact sheet of them all, labelled with their times: one image to read instead of N.

`shot --no-pointer` (a screen shot, --burst too) and `record --no-pointer` leave the pointer out, for stills and videos meant for people (no arrow on the app, none parked on a hover state): it is hidden (Hyprland's cursor:invisible), a frame without it awaited (up to a second), and shown again after, as it was, also on a failure or Ctrl-C; a recording keeps it hidden until `record stop`. `pointer hide` (or `up --no-pointer`) hides it in the box until `pointer show`, over config reloads and theme switches (omarchy-theme-set reloads). Hidden, it still moves and clicks where it is told, focus still follows it, and peek's marks still show it; `wait` and `--changed` leave out where it is, as they do when it shows.

`shot --changed` (or `--window SEL --changed`) is a crop of what changed since the last whole shot of the same screen or window (`shot` without -g, --fit, --zoom or --monitor, or --changed; with --fit 0 while shot-fit is set), 16 px around it; stderr says where it is (`click --in` maps it) and, when it changed in places far apart, each. Nothing changed: no image, nothing on stdout, exit 0, said on stderr. No earlier shot of it (or another size or mode since): a whole shot, said why. A caret blinking alone (4 px thin, 40 long at most) and where the pointer was before it moved are not changes; --ignore "X,Y WxH" (up to 16, in the shot's coordinates: the window's with --window) leaves out an animation or a caret elsewhere. --since SHOT compares with that whole shot instead (not from a jail).

More monitors: `up --monitor SPEC` (repeatable) or `monitor add SPEC` on a running box. SPEC is WxH[@HZ][,scale=S][,right|below|X,Y]: placed right of the last one made by default, or below it, or at X,Y in the layout (which starts at 0,0 on the main screen: no left or above). Scale 1 to 4; Hyprland may round it to a whole-pixel size (2560x1440 at 1.5 becomes 1.6). The main screen (--size, `mode`) is HEADLESS-2; the others HEADLESS-3, -4, ... (or --name); on NVIDIA, where a box draws on Wayland outputs, WAYLAND-1 and WAYLAND-2, -3, ... (no --name); there a headless output a program makes itself (`hyprctl output create headless`) is listed 0x0, which `monitor list` and `shot` say, naming a box on another GPU to test it in. `monitor remove NAME` unplugs one: Hyprland moves its workspaces to the others. They survive a config reload, and one placed right or below moves when the one before it changes size (`mode`, said) or goes; an X,Y one stays. Coordinates (click, drag, pointer, pixel, -g) are the layout's (`pixel` refuses a point in a gap between them); `shot --monitor NAME` takes one monitor (a shot of a mixed-scale layout comes out at the highest scale: --fit). `peek` shows the main screen, `peek --monitor NAME` another: a window per monitor, tiled on the workspace, each marking the clicks and pointer on its own monitor (keys on all); one whose monitor drops (`output drop`) says it is gone, and shows it again once it is back; the whole layout at once is `shot`. An interactive box's monitors are windows on your desktop, on its workspace, placed in the box as a headless box's; on your screen the box's layout scaled as a whole, as display settings draw it: one scale for every window (at most 1), the picture centred on the monitor its main window is on, the main window floated for it (it tiles again when the last monitor goes); each `monitor add` and `remove` lays it out again. Each window is a view of its monitor: the monitor's size in the layout, which the bar and apps see, is the one asked for (the main screen's --size, a SPEC's), its mode its window's pixels at a scale of at most 1 (`monitor list`). Resizing a window changes its view's scale, not the monitor (a window of another shape shows it smaller along one side); closing one unplugs it. They need aquamarine's fix, as NVIDIA boxes do, and omabox's build of it puts your pointer on the monitor whose window it is in and keeps your cursor shown from one window to the next (`monitor add` says when a box's aquamarine does neither).

#### omabox pixel

The colour of a pixel on the screen, in a window or in a shot, as `#rrggbb`: no image tool of your own.

Examples:

```
$ omabox pixel 40 12
$ omabox pixel --json --window myapp 10 10 200 80
```

```
omabox pixel [-b NAME] [--window SEL | --active | --in SHOT] [--json] X Y [X Y]...   the colour there, #rrggbb
```

`omabox help pixel` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

--fit N scales a shot's image down to N pixels on its longest side (a scaled screen's image is its layout times the scale: 2560 px for a 1280 px layout at 2). --zoom N (2-16, with -g) shows each pixel of a small crop as N x N, unblended: a 1 px border, a glyph's edge; `click --in` maps it back. -g "X,Y WxH" (or X,Y,W,H) crops: the screen's, or with --window the window's own coordinates; a region past the edge is cut to it, said on stderr (one with nothing inside is refused). At a fractional scale the image is the screen's own pixels from the one its start rounds to (30 at 1.25 is 37.5 px: from 38), not grim's blend, so find --image finds a crop where it was cut; the region recorded (stderr, --json, click --in) is the one asked. A cropped or scaled shot says so on stderr: `click --in SHOT X Y` (and `drag`, `pointer --in`) take that image's pixels (a window shot follows the window if it moved). Screen shots show the pointer (--no-pointer: not this one; `pointer hide`: none until `pointer show`); window shots never do. -o makes the file's folder if it is missing. An action `--in` a screen shot (click, scroll, drag, pointer) is refused, exit 1, when what is at its point is not what was there at the shot: another window or layer over it, or the window moved under it ("the screen changed at X,Y since SHOT: then on ..., now on ...; take a new shot"). A change elsewhere on the screen (a toast, a clock, a window away from the point) is not. One Hyprland read per point; a --burst frame is not checked.

`pixel X Y` reads the box's own pixel (#rrggbb), with no shot: a colour off a scaled shot, or one read by eye, is not the one drawn. Several points in one call print "X,Y #rrggbb" each. The screen's pixels are what is shown: the pointer drawn over them, a window through Omarchy's opacity; --window reads that window's own pixels (its coordinates, covered or not). --in SHOT maps that image's pixels.

#### omabox windows

The box's windows: where they are, which workspace, what covers them.

Examples:

```
$ omabox windows
```

```
omabox windows [-b NAME] [--json]                      the box's windows, where they are, what covers them
```

`omabox help windows` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

#### omabox wait

Wait for a still screen, a window, a layer or a command, instead of sleeping.

Examples:

```
$ omabox wait window myapp --focused
$ omabox wait still
```

```
omabox wait [-b NAME] [--timeout 10s] [--json] COND   until COND holds (exit 0), 124 if not in time
       COND: still [--quiet 300ms | --like SHOT] [-g GEOM | --window SEL] [--ignore GEOM]... [--strict]
             | change [--since SHOT] [-g GEOM | --window SEL] [--ignore GEOM]...
             | window SEL [--gone | --focused] | layer NAMESPACE [--gone] [--monitor NAME]
             | image FILE [--gone] [--similar 0.95] [-g GEOM | --window SEL]   find --image's, polled
             | until -- CMD [ARG...]
             | job [JOB] [--gone] | log [JOB] RE [-i]   a run -d job's end; a line in its log
             | tree TEXT [--window SEL | --layer SEL] [--gone] [--shot FILE]
             | log LOG (RE | --grep RE) [-i] [--since OFFSET]   a new line in a box log: shell, hyprland, ...
             | notification RE [-i] [--since OFFSET]   a notice whose summary or body RE matches
omabox wait [-b NAME] [--json] for DURATION            a fixed time, said as one (no box needed)
```

`omabox help wait` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--layer SEL (or -l SEL): a layer surface (the bar, a panel, a menu): its namespace, address:0x... or pid:N

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`find --image FILE` finds a picture where there is no accessibility tree (the shell, its plugins, the bar, a terminal): FILE is a PNG, best a crop of a shot of the box (`shot -g "X,Y WxH" -o FILE`), whose comment records the scale it was taken at. Each match is a line `X,Y WxH SCORE` in the layout's coordinates, in reading order (`-g`'s, click's, shot -g's), 1 the same pixels; exit 1 none, with the best score seen and where. Several: all listed (20, --all every one) and said on stderr, never one taken for you. --similar (0.95) is the score a match needs: normalised correlation of the colours, less for another contrast or tone (a grey switch is not its blue self); an image of one colour by its difference, transparent pixels not compared. A box drawn at another scale than FILE's resizes it and says so, then needs 0.8 unless --similar says; its one match with another place within 0.05 of it is a near tie (a look-alike scores that close once scaled), said on stderr and as --json's near_tie. -g looks in a region, --window SEL in that window's own pixels (covered or not). `click --image FILE` clicks the middle of the one match (--offset DX,DY beside it: a label's field), several exit 2 numbered for --index N, a near tie exit 2 with both (a crop shot in this box tells them apart); `wait image FILE [--gone]` polls for it, a near tie not counted as there (0, 124, 1 as the other waits). Each takes a frame and searches it in about 50-100 ms. A jailed agent's FILE is read by its own omabox.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

`wait layer NAMESPACE`: until a layer of that namespace is drawn (a 1x1 one is a closed menu, not drawn); its line says where and on which monitor (`at 0,0 1920x1080 on HEADLESS-2`), each one when there are several (a bar on every monitor). --monitor NAME waits for one on that monitor (`omabox monitor list`), --gone for none there; one the box does not have is said, with the ones it has. `wait until -- CMD`: until CMD, run in the box, exits 0 (tried every 100 ms): a server answering (`curl -fsS http://127.0.0.1:PORT/`), a file written, a process gone (`sh -c '! pgrep -x NAME'`). CMD runs in the box, where the host's paths are not (its /tmp and HOME are its own): a command not found there (127) or that cannot run (126) ends the wait at once, "unknown"; one that names this box's folder or your $TMPDIR is said before waiting. A wait that did not succeed ends with the last try's last lines of stderr. `wait tree TEXT`: until the accessibility tree holds TEXT, matched as `tree --find` matches it (any case, names whole, [STATE ...] at its end any of the line's states: `'"Dark mode" [checked]'`), read about every 100 ms in the window --window SEL picks (none: the active one, picked again at each read) or on the layer --layer SEL (-l SEL): satisfied at the first read holding it, the line saying the one holding it, so a state that lasts a moment (a toast, a sheet) is caught. --gone: until two reads in a row do not (or the window or layer is gone). A window not there yet, or not on the bus yet, is waited for. A 124 says what the tree had instead: the lines holding TEXT's name (its "quoted" part, or what comes before its states) when there are any, else why (omabox-tree's words, "no window matches SEL"). --shot FILE takes a shot (as `shot -o FILE`) the moment it holds, named on the line. A read is given the time left (half a second at least), so an app that hangs keeps --timeout: "did not answer in time (busy or hung?)".

`wait job [JOB]`: until the command of `run -d` job JOB (its pid, as `jobs` lists it; none: the latest `run -d`'s) has exited, satisfied with how it ended ("exited with status 0", "was killed by SIGTERM (143)"), at once for one that ended already; --gone: until nothing of its session runs either (what it forked: an app a launcher left). `wait log [JOB] RE [-i]`: until a line of the job's log (as `log run [JOB]` has it, every line from its first: one there already counts) matches RE (grep -E; -i: either case), satisfied with that line; a job that ended with no such line is unknown (exit 1), as nothing more will come. Each tried every 100 ms. Never a host `pgrep` or a loop over the log file. `wait log LOG RE [-i]` (LOG a box log, as `log` names them: shell, hyprland, apps, journal, ...; RE also as --grep RE): until LOG gets a line RE matches written after the wait began, printed with it (a plugin's line in the shell log). A box log has lines from before: they do not count, and a 124 says one that was there (`--since 0` counts the whole log). --since OFFSET reads from that byte; --json's offset is where the line found ends, for the next wait's --since. A log begun anew meanwhile (restart-shell starts the shell's) is read from its start, said. Hyprland's new lines come from `hyprctl rollinglog` (its file is written 8 KiB late), every 250 ms: no --since there. `wait notification RE [-i]` (#430): until a notification reaches the box's server (as `log notifications` has it) whose summary or body RE matches (grep -E, each with its newlines as spaces; not its app name), printed with it; --json adds the record (`notification`: its id, hints, actions). One sent before the wait does not count, and a 124 says one that was there (`--since 0` counts the whole log; --json's offset is the next wait's --since). One sent with no server counts too: its line says `(no id) ... -- not shown: WHY`. `wait for DURATION`: that long, then "satisfied: waited ..., a fixed time": for a time that is the point (a timer under test), where a foreground sleep is blocked. Not to let an app settle: wait for what it does (still, change, window, job, log, until).

#### omabox tree

A window's or a layer's accessibility tree, as text: ask before you look.

Examples:

```
$ omabox tree --find 'dark mode'
$ omabox tree --window myapp --json
```

```
omabox tree [-b NAME] [--window SEL | --layer SEL] [--find TEXT] [--json] [--all]   a window's (or a layer's) accessibility tree as text
```

`omabox help tree` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--layer SEL (or -l SEL): a layer surface (the bar, a panel, a menu): its namespace, address:0x... or pid:N

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`tree` prints a window's accessibility tree as text (--window SEL; none: the active window): a line a node, `role "name" 'text' =value [states] @X,Y WxH`, indented by level; anonymous containers, hidden nodes and what lies outside the window are left out (--all keeps them). The bounds are the window's own coordinates: `click --window SEL` at their middle lands on that node (`click --find TEXT` finds it and clicks there). An unnamed control takes its label's name. Ask first, read whole later: --find TEXT prints only the lines holding TEXT (any case, not in the bounds), each after its ancestors (`list > list item "Beta" [selected] @12,354 1872x22`); exit 1 when none does. TEXT ending in [STATE ...] also finds a line with each of those states among its own, in any order, the rest of TEXT before them: `"Dark mode" [checked]` finds `check box "Dark mode" [focused checked]`, never `[unchecked]`. The text view cuts a name or text at 80 characters and a value at 40 (ending in …); --find matches them whole, and --json carries them whole (up to 4000 characters). --json: an array, one object a node printed. GTK, Qt and egui/winit (AccessKit) apps have a tree (`tree` sets org.a11y.Status.IsEnabled, which Qt and AccessKit wait for). AccessKit needs accesskit_unix 0.22+ (eframe 0.37+) with at-spi2-core 2.61+: an older one waits only for ScreenReaderEnabled, which those no longer have (`tree` sets it where it is), so it never joins the bus and has no tree, said so; update the app's AccessKit. Chromium and Electron only when started with --force-renderer-accessibility; terminals have none: "no accessibility tree", exit 1. An app that publishes only some of its windows (egui's root viewport, not its child ones): a window it does not publish has no tree, and its only one stands for a window of another title only at that window's size, and when no other window of the app is that size (else "cannot be told"), exit 1. --layer SEL (or -l SEL) reads a layer surface instead (the shell's bar, panels, menus, a plugin's panel): its namespace (omabox hyprctl layers), address:0x... or pid:PID. Its bounds are the screen's coordinates: a plain `click X Y` at their middle lands on that node. Quickshell publishes them from 0.3.2 on, and only items that set an Accessible role: "the layer publishes no accessible items", exit 1, when none does (Omarchy's own bar). Two layers of one process with one size cannot be told apart (their frames have no names) unless one of them holds the keyboard (a launcher, an Omarchy 4.5 bar popup): said so, exit 1.

#### omabox check

Visual checks: a scenario's checkpoints against a baseline, said same or changed.

Examples:

```
$ omabox check run --approve -- ./scenario.sh
$ omabox check run -- ./scenario.sh
```

```
omabox check run [--approve [--runs 3] | --json] [--base DIR] [-o DIR] [--speck N] [--only ID,GLOB...] [--report-scale N]
                 [UP OPTIONS] -- SCENARIO [ARG...]     a visual check: the scenario's checkpoints against a baseline
omabox check point ID [-b NAME] [--window SEL] [-g "X,Y WxH"] [--ignore "X,Y WxH"]... [--timeout 15s] [-o DIR]
                   [--expect TEXT]... [--expect-tree TEXT]... [--expect-image FILE]... [--expect-cmd -- CMD [ARG...]]
                                                       a checkpoint, in a scenario: once still, a shot (and the tree)
omabox check wants ID...                               in a scenario: does this run take any of them (--only)? exit 0 yes, 1 no
omabox check diff A.png B.png [--ignore "X,Y WxH"]... [--speck 32] [-o MARKED.png] [--report R.png [--report-scale N]] [--json]
                                                       what differs, as a check sees it
```

`omabox help check` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-o (or --output) names what the command writes.

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--clean: --stock plus the run-to-run freezes, a desktop where only what is tested moves, for shots compared across runs (`check`): a #ff00ff wallpaper (no theme has it: any of it inside a window or the bar is a hole), the bar's clock frozen at "Friday 12:00" (in its place, at its width), no pointer, no network (--net connected gives it back), animations off (over reloads too), and no name of yours: the user is `user` (no full name) and the host `omabox`. --keep LIST takes any of animations, bar (yours), clock, fonts (yours), identity (your user and host names), locale (yours and your timezone), pointer, wallpaper (the theme's) back. A theme set later in the box brings that theme's wallpaper. On a plain box: no bar, theme or clock (--keep bar and clock refused), and the sentinel is its Hyprland's background colour (misc:background_color), not a wallpaper.

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`check` compares an app's or a plugin's look with a baseline, so a person need not look. A SCENARIO is a script of yours that sets the box up, drives it with omabox commands and calls `omabox check point ID` where a shot should match (once still, full size whatever shot-fit: the screen, -g, --window SEL with its tree; --ignore leaves a region out, in -g's coordinates: the window's with --window, else the screen's); `check run` gives it a fresh `up --clean` box each run (UP OPTIONS; OMABOX names the box). --approve runs it 3 times and writes the baseline to --base DIR (./omabox-check): what most runs showed, where they differed "unstable" and left out from then on, and baseline.png, every checkpoint kept in one image (or pages): look at it before you keep the baseline (a wrong screen most runs showed is kept too). Without --approve it runs once and says for each checkpoint same, changed (each region "at X,Y WxH", the tree's changes; "as ID" for one an earlier one had), holes, new or missing; when any changed, look at report.png first (each change cropped beside its baseline). Exit 0 all same, 1 not, 2 called wrongly or could not run (an option, a file, no box, no magick), 3 the scenario failed, 4 no baseline. Shots are compared exactly but for specks (stray parts smaller than the approve runs differed by, said under "same"), and searched for holes (the #ff00ff wallpaper inside a window, the bar or a popup). --only ID,GLOB (while working on one screen; a whole run before the work lands) checks only the checkpoints it names, the others skipped (not missing): check point takes no other, and the scenario skips a section with `omabox check wants ID...` (exit 1: none of them wanted; the list is in OMABOX_CHECK_ONLY); with --approve it replaces those in the baseline, every other kept as it was. --report-scale N (2 to 4) also draws report.png (baseline.png at --approve) N times its size, report@Nx.png, for people (a README, a site, a video): the same layout, crops at the shots' own pixels on a box of scale N; report.png stays the agent's. Proofs on a checkpoint: --expect TEXT says in words what that screen must show ("the menu is open, Beta selected"; not checked: said under its line in check run and --approve, and on its card in report.png and baseline.png, for whoever judges a change or approves a baseline); --expect-tree TEXT fails it when `tree --find TEXT` of its --window finds nothing; --expect-image FILE when `find --image FILE` (on the screen, in --window's own pixels) finds no match; --expect-cmd -- CMD [ARG...] (last: the rest is the command) when CMD in the box exits non-zero or outlasts --timeout. A failed proof is its own result, "proof ID: proof failed: WHAT (WHY)", apart from changed, even where the pixels are the baseline's (exit 1); --approve keeps no run where a checkpoint's proof failed, and when it failed in every run approves nothing (exit 1, the baseline as it was). Give both kinds: a command says "locked" over a black lock screen, and a wrong screen approved stays "same". `check diff A B` compares two shots of yours the same way. More (times and dates, specks, holes): the omabox skill's reference.md, "Visual checks". Not inside ai-jail yet.

#### omabox record

A video of the box, with marks, captions, input drawn in and a contact sheet.

Examples:

```
$ omabox record start -o demo.mp4
$ omabox record mark 'Settings open'
$ omabox record stop --sheet --show-input --captions
```

```
omabox record [-b NAME] (start [-o FILE] [--monitor NAME|all] [--fps 30] [--crf 18] [--no-pointer] [--audio] [--glide DURATION]
              | mark TEXT [--hold DURATION] | hold DURATION | stop [SHEET] [POLISH] | status [--json])   a video of the screen
omabox record [-b NAME] [-o FILE] [--monitor NAME|all] [--fps 30] [--crf 18] [--hold 1s] [--no-pointer] [--audio] [--glide DURATION]
              [SHEET] [POLISH] -- ACTION...   one action, recorded
omabox record [-b NAME] [-o FILE] [--monitor NAME|all] [--fps 30] [--crf 18] [--no-pointer] [--audio] [SHEET] [POLISH]
              --for DURATION   the screen for that long, no action
omabox record [-b NAME] sheet VIDEO [-o PNG] [FRAMES] [--fit N]   a contact sheet of any video, a box up or not
            SHEET: --sheet [FRAMES] [--fit N]   the recording's contact sheet, FILE.sheet.png
            FRAMES: [--from T] [--to T] [--frames 15 | --every DURATION | --every-frame | --changed] [-g "X,Y WxH"]
            POLISH: [--show-input] [--captions] [--cut-idle [1s]]   clicks, pointer, keys and marks drawn in; still stretches cut
```

`omabox help record` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-o (or --output) names what the command writes.

--audio: the box's own PipeWire, WirePlumber and pipewire-pulse (PipeWire and Pulse apps both play), its only devices a speaker nobody hears (omabox-speaker, a null sink: the default output) and a silent microphone (omabox-mic, the default input). Nothing reaches your audio: a box has no /dev/snd and its own runtime dir (its sockets, never yours). `audio` says whether the box made a sound, `record --audio` puts it in the video (AAC). Logs: `log audio`. Without it a box has no audio.

`record start` records one output of the box (its main screen, or --monitor NAME) at its own pixels: a box at `--size 3840x2160,scale=2` gives a 4K video. `record stop` ends it and prints the file, an MP4 (H.264) at a steady --fps (30), -o FILE or a new one in $TMPDIR. `record -- ACTION` (an omabox command: keys, click, run -d ...) records that one action and --hold (1s) after it. Needs wf-recorder and ffmpeg; both run in the box. One recording a box at a time; `record status` says if one runs. `--crf N` (with start, -- ACTION or --for) is the video's H.264 quality, 18 by default: small files, easy to read. Footage that will be zoomed or encoded again wants 8-10 (finding 602: a 4K terminal take at 8 is 1.7 times the size, 64 dB PSNR where 18 has 56); 0 is lossless, but H.264's High 4:4:4 Predictive, which browsers do not play. The raw stream it is made from takes the same when lower than 14. The H.264 is libx264's; an ffmpeg without it (Fedora's ffmpeg-free, openSUSE's ffmpeg) makes it with openh264, said at start and stop (doctor says which): still an MP4 (H.264), --crf N its fixed quantiser (QP N: about libx264's CRF N quality, at about 1.7 times the bytes), no --crf 0, and at most 4096x2304's pixels a frame (a monitor past it refused, a layout past it scaled down to fit). `--monitor all` records every monitor as one video of the whole layout, as `shot` takes it: each at its place, at the highest scale of them (a lower-scale one scaled up), turned as it is shown, black between them; the video the size of the screen's shot (one black edge more if a side is odd). A wf-recorder each, in step by their frames' own times: a change drawn on two monitors at once is in the same frame, give or take one (each monitor draws on its own clock), and marks and sheets work as for one. Past H.264's largest frame (8192x4352's pixels, 16384 a side) the whole is scaled down to fit, said at start; a big layout takes `stop` longer to put together. `record mark TEXT` (while one runs) notes TEXT at the time it is called, in the video's own clock: ms from its first frame, exact to a few ms (the screen's own frame times, not when start returned). Mark just before what it names (a scene, a key press: what is drawn after shows up from that time on). `record stop` writes them beside the video, FILE.marks.tsv (ms, wall-clock time as `events` has it, text) and FILE.vtt (captions, each mark until the next), and says where. Captions burnt in: `ffmpeg -i demo.mp4 -vf subtitles=demo.vtt out.mp4` (players load demo.vtt beside demo.mp4 by themselves); a cut at two marks' ms: `ffmpeg -ss 4.200 -to 9.850 -i demo.mp4 -c:v libx264 cut.mp4`. A script of omabox calls and sleeps runs longer than its sleeps (each call takes its time): marks show where it drifts. Time in a recording, never a sleep: `record --for 5s` records the screen for 5 s with no action (start, a hold, stop: something that moves by itself). In a take, `record hold 2s` (between start and stop) returns once the video has 2 s more from when it was called, in the video's own clock (its frames' times, not the wall clock): a box slow to give frames, or a script slow to call, never shortens the pause the viewer sees (the time before the call is in the video too); it says the span ("held 4.210s to 6.210s"). `record mark TEXT --hold 2s` is the mark, then that hold from it (60s at most; --for and hold 60m). A bare number is seconds. `wait still` is no hold: it returns at once on a still screen and runs to its timeout under a clock or a spinner. `record stop --sheet` (or `record --sheet -- ACTION`) adds FILE.sheet.png, and `record sheet VIDEO` makes one of any video (ffmpeg reads it in the box; with no box named and none up, here, sandboxed): a contact sheet to read instead of watching, --frames N (15) from the first to the last or one each --every DURATION, each labelled with its time and the marks since the frame before it ("> 4.20s TEXT"), 5 a row, 320 px tiles or --fit N (shot-fit's by default) for the whole sheet. An agent checks a take from it and fixes its script. Frame by frame (#260): `--from T --to T` (times in the video) keeps the sheet to that stretch (--frames and --every spread over it), `--every-frame` takes each of its frames (100 at most), `-g "X,Y WxH"` shows only that region of each (in the video's pixels; a small one enlarged pixel for pixel, up to 8 times), and `--changed` its first frame, then each frame where the region (without -g, the whole frame) differs from the one before by more than H.264's noise (a pixel 6 of 255 off in Y, U or V): a 100 ms glitch is its first frame and the one after its last. Each tile then says its time to the ms and its frame number ("12: 9.433s f283"). Marks outside the stretch are left out. With no box named (-b) and the default one not up, `record sheet` runs ffmpeg here, in a bwrap sandbox of its own (#279): no network, no environment (no display to open), the system's /usr read-only, the video as an fd and a working folder in ~/.cache/omabox, nothing else; the same sheet. `record --audio` (an up --audio box) adds the box's sound, from its speaker, as AAC in the MP4: in step with the picture (ffmpeg's first samples stamped and put in the video's clock: a sound starts within ~15 ms of a change drawn at the same moment), with --monitor all too. A player is slower to start than a terminal to draw: pw-play's first sound came ~60 ms after its terminal changed. Polish for people watching it (#176): `record start --glide DURATION` makes click, pointer and drag glide there in that time while it records (unless --steps), the pointer seen moving. `record stop --show-input` draws what click, scroll, pointer, drag and keys did into the video, as peek shows it, at the times it happened: a ring over the pointer following each move (gone 3 s after the last), a ripple from each click (its button named but for left), key captions at the bottom (typed text a character at a time; keys 1.5 s apart in one caption; --pass as *); `--captions` the marks' texts at the top, each until the next (in a layout, both on the main screen). `--cut-idle [DURATION]` cuts every still stretch longer than DURATION (1s) to that: no frame change (a blinking caret or a clock digit is still), no input (with --show-input, 3 s after it while it is drawn), no mark, no sound; whole frames, the sound by the same times, the marks and captions moved with them. The input comes from omabox's own commands (`run`'s app moving its own windows is not input). A video is at most 16 GiB (an hour of 4K at 36 Mbit/s): omabox copies no more out of a box, and `stop` says so and keeps a larger one in the box. Each ffmpeg step of `stop` and `sheet` has a time limit (60 s, and 5 s more a second of 1080p30 recorded; ffmpeg 9.0.1 can deadlock): one that runs out is killed and run once more, then said. When the video's encode runs out twice, `stop` copies the raw H.264 into the MP4 instead, not re-encoded, and says what that video lacks (a steady fps; the sound, input, captions, cut or layout asked for; it is larger); only when that copy fails too does it fail, the recording's raw files kept in the box. Inside ai-jail all of it works through the broker: the jail's own omabox resolves -o and opens the video, its marks, captions and sheet (and `record sheet`'s video) itself, and the broker writes and reads them only through those, never at a path the jail names; one stopped outside the jail goes to ~/.local/share/omabox/records.

`shot --no-pointer` (a screen shot, --burst too) and `record --no-pointer` leave the pointer out, for stills and videos meant for people (no arrow on the app, none parked on a hover state): it is hidden (Hyprland's cursor:invisible), a frame without it awaited (up to a second), and shown again after, as it was, also on a failure or Ctrl-C; a recording keeps it hidden until `record stop`. `pointer hide` (or `up --no-pointer`) hides it in the box until `pointer show`, over config reloads and theme switches (omarchy-theme-set reloads). Hidden, it still moves and clicks where it is told, focus still follows it, and peek's marks still show it; `wait` and `--changed` leave out where it is, as they do when it shows.

#### omabox audio

Listens to a box with `--audio` and says whether it made a sound, when and how loud.

Examples:

```
$ omabox audio 3
```

```
omabox audio [-b NAME] [DURATION] [--json]             an up --audio box's sound for DURATION (3s): when, how loud
```

`omabox help audio` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--audio: the box's own PipeWire, WirePlumber and pipewire-pulse (PipeWire and Pulse apps both play), its only devices a speaker nobody hears (omabox-speaker, a null sink: the default output) and a silent microphone (omabox-mic, the default input). Nothing reaches your audio: a box has no /dev/snd and its own runtime dir (its sockets, never yours). `audio` says whether the box made a sound, `record --audio` puts it in the video (AAC). Logs: `log audio`. Without it a box has no audio.

`audio [DURATION]` listens to the box's speaker for DURATION (3s, up to 10m) from now, 100 ms at a time: "sound for 1.1s of 3s: peak -21.1 dBFS, RMS -24.5 dBFS while it sounded; at 0.4-1.5s", or "silence for 3s". The speaker is a null sink, exact zeros while nothing plays: anything above -70 dBFS is a sound. --json: sound (true/false), sound_s, peak_db, rms_db, spans ([from, to] seconds), levels (each window's t, peak_db, rms_db; null for silence). Exit 0 either way. Start it, then make the sound (`omabox run -d -- APP`, a key), or record with --audio and check the video.

#### omabox log

A box's logs: Hyprland's by default, or the shell's, the apps', the last `run -d`'s. `-f` follows them.

Examples:

```
$ omabox log shell --grep qml -n 20
$ omabox log apps -f
```

```
omabox log [-b NAME] [LOG...|all] [-n 100|all] [--grep RE [-i]] [-f]
                                                       a box's logs: hyprland (the default), shell, apps,
                                                       autostart (a desk box's), run, events, keyring, labwc,
                                                       systemd, audio, polkit, gdb, journal, notifications,
                                                       box, reap
omabox log [-b NAME] run [JOB] [-n 100|all] [--grep RE [-i]] [-f]   a run -d job's log: JOB its pid (jobs), none the latest
omabox log [-b NAME] notifications [--json] [-n N] [--grep RE [-i]] [-f]   what apps sent the notification server
omabox log [-b NAME] gdb --crash                       only the backtrace of the thread a crash hit
```

`omabox help log` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-f (or --follow): on until the box goes down

`log` prints the last -n lines (100) of each log named, of a box that died too; run is the latest `run -d`'s (`run JOB`: that job's, by its pid as `jobs` and `run -d` say it or any pid of its session, ended too; an unknown one names the jobs there are), apps what Omarchy's launcher started, journal what programs sent the box's journal sockets (/run/systemd/journal: dbus-broker, `logger` and `logger --journald` (`-t omarchy-shell` goes to shell), `/usr/bin/systemd-cat` (the bare name writes ~/ID.log), units' output; at most 4 MB, then journal.1.log), box bwrap's. shell's lines carry their time (YYYY-MM-DD HH:MM:SS.mmm, Quickshell's --log-times; the launcher's `logger` lines too, not what Quickshell prints outside its log) as `omabox events`' do (HH:MM:SS.mmm); Hyprland's have none. --grep sees the time as part of the line. -f (or --follow) follows them until the box goes down (-n then counts lines before --grep). Hyprland writes its log file 8 KiB at a time: `log hyprland` adds the newest lines from `hyprctl rollinglog` (its last 4 KiB; stderr says when the file is further behind), while -f gets them late. `log gdb --crash`: only each crash's signal and the backtrace of the thread it hit (-n and --grep then apply to those). `log notifications` (#430): what reached the box's notification server from up on, whatever server it is (the shell's, a plain box's, none yet), a line each: `notify #ID APP: "SUMMARY" "BODY"` with its hints (urgency, category, desktop-entry, ...), actions and timeout, the id its server answered with (`(no id)` and why when none did: no server, no reply in 5 s; one that comes later, up to 25 s, is joined: `notify #ID (replied after 6.0 s)`); `close #ID` (an app's CloseNotification), `closed #ID expired|dismissed|closed by CloseNotification` and `action #ID KEY` (the server's). GTK's GNotification is recorded too (GLib sends it as a Notify in a box). --json: one JSON object a record (time, event, id, error, serial, sender, app_name, replaces_id, app_icon, summary, body, actions, hints, expire_timeout; reply_time when the id came late). -n and --grep count records, --grep matching the text line. Texts are cut at 16 KiB; the log stops at 16 MB.

#### omabox events

What the box's Hyprland reported, stamped: mark a point, act, then read what came after or wait for one event.

Examples:

```
$ omabox events --mark m1
$ omabox events --since m1 --until 'openwindow>>' --timeout 5s
```

```
omabox events [-b NAME] [--since MARK] [--grep RE [-i]] [-n N] [--json]   Hyprland's events
omabox events [-b NAME] --mark [MARK] [--json]         from here: prints the offset, keeps MARK for --since
omabox events [-b NAME] [--since MARK] (--until RE [--timeout 10s] | -f) [--json]
```

`omabox help events` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-f (or --follow): on until the box goes down

`events`: what the box's Hyprland reported on its event socket (activewindow>>, urgent>>, ...) from its start, never cleared. --mark MARK takes "from here" (a byte offset: safe while events come); --since MARK (a mark, an offset, or 30s/2m/1h ago) reads from there. --grep and --until match the EVENT>>DATA part (grep -E). --until: the first matching event from --since (or from now), printed: exit 0, 124 none by --timeout, 1 the box went down; -f (or --follow) follows until the box goes down.

#### omabox gpu

GPU time of one box's processes, to see what your app costs to draw; `release` takes down the boxes on a GPU before it goes to a VM.

Examples:

```
$ omabox gpu 10
$ omabox gpu release nvidia
```

```
omabox gpu [-b NAME] [DURATION] [--json]               GPU engine time of this box's processes (default 5s)
omabox gpu release GPU                                 take down the headless boxes rendering on that GPU
```

`omabox help gpu` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Sizes: WxH is @60; `host` copies your focused monitor's size and refresh rate (scale stays 1). `,scale=S` (1 to 4, as a monitor's) gives the main screen a scale, headless only: `--size 3840x2160,scale=2` is a 4K screen laid out as 1920x1080, the bar and apps their usual size in twice the pixels, so a `shot` of it is 3840x2160 (coordinates stay the layout's: `click --in` maps a shot's). `mode WxH` without one is scale 1. Hyprland may round a scale to whole pixels (`mode` says so). Measure rendering cost with `omabox gpu` (and `omabox cpu`) in a box whose mode matches your monitor.

`gpu release GPU` (a PCI slot, or nvidia, amd, intel: `omabox config gpu` lists them) takes down every headless box rendering on that GPU, naming each, so it can be handed elsewhere (a VM: a box holds its render node, and on NVIDIA its /dev/nvidia*). Interactive boxes are left alone (they render on the desktop's GPU), and so are boxes on other GPUs. An `up` or `down` in progress is waited for first. Each box's GPU is in `gpu`, `ls` (with more than one GPU, or when it is a fallback, and why) and `--json` (render). `gpu` reads the kernel's per-process DRM counters (AMD; Intel untested). NVIDIA's driver has none: there it is the driver's own sampling through nvidia-smi pmon, whole seconds, each process's share of the GPU as seen once a second (`--json` says which, as source).

#### omabox cpu

CPU and memory of a box's processes, per thread with `--threads`.

Examples:

```
$ omabox cpu --app myapp --threads
```

```
omabox cpu [-b NAME] [DURATION] [--settle DURATION] [--pid PID | --app NAME] [--threads] [--json]
                                                       CPU (% of one core) and memory of this box's processes (default 5s)
```

`omabox help cpu` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Sizes: WxH is @60; `host` copies your focused monitor's size and refresh rate (scale stays 1). `,scale=S` (1 to 4, as a monitor's) gives the main screen a scale, headless only: `--size 3840x2160,scale=2` is a 4K screen laid out as 1920x1080, the bar and apps their usual size in twice the pixels, so a `shot` of it is 3840x2160 (coordinates stay the layout's: `click --in` maps a shot's). `mode WxH` without one is scale 1. Hyprland may round a scale to whole pixels (`mode` says so). Measure rendering cost with `omabox gpu` (and `omabox cpu`) in a box whose mode matches your monitor.

`cpu` is `gpu`'s twin for CPU and memory: each process in the box's pid namespace (never the desktop's, which a host `top` or `pgrep` mixes in), its CPU over DURATION (5s) as % of one core (100% is one core busy; the rows add up to the total), its RSS and PSS (shared pages split among the processes sharing them: the total is what the box holds) as last seen. Sampled every second: a process that started in the window counts all its time, one that exited keeps what was seen up to its last sample (both said). --settle DURATION waits that long before the window (an app's start-up left out). --pid PID: one process, as the box numbers it (`omabox run -- ps -e`) or its host pid; --app NAME: the processes of that name (their /proc comm, the first 15 bytes). --threads, with --pid or --app: each of their threads too, under its process, by its name (comm: a Qt Quick app's GUI thread apart from its QSGRenderThread), over the same window; one row per thread, names repeated or not, its tid as the box numbers it, started or exited said as for processes. --json: percent by name (as `gpu`'s), processes (pid, host_pid, name, cpu, rss_kb, pss_kb, started, exited; with --threads, threads: tid, host_tid, name, cpu, started, exited) and total.

#### omabox gdb

Every thread's backtrace of the box's Hyprland or shell, hung or stopped too; `--watch` catches a crash into `omabox log gdb`.

Examples:

```
$ omabox gdb
$ omabox gdb --shell --watch
```

```
omabox gdb [-b NAME] [--shell | --pid PID] [--watch | -- GDB ARGS]   a backtrace of the box's Hyprland (or shell)
```

`omabox help gdb` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`gdb` prints every thread's backtrace of the box's Hyprland (--shell: the shell; --pid PID: a process of the box), stopped or deadlocked too, and leaves it as it was; -- ARGS replace the backtrace with gdb's own (-ex 'info threads'). --watch attaches until a crash: the backtrace of the fatal signal goes to `omabox log gdb` (the thread it hit first, then every thread; `log gdb --crash` for that one alone), then the crash goes on. gdb gets CAP_SYS_PTRACE in the box's user namespace only: it traces the box's processes, never the host's. No symbols beyond the binaries' own (debuginfod off).

`omabox pid`, `which` the other way round: the host PID of the box's Hyprland (the default) or its shell, for /proc/PID/maps, perf or strace on the host; --in-box the PID as the box numbers it (`gdb --pid`, `omabox run -- kill`). --json: {box, process, pid, box_pid}. Nothing on stdout and exit 1 when it is not running.

### Keys and the pointer

#### omabox keys

Key combos for Hyprland binds and the focused app, any Unicode text, or a password from your environment, never on a command line.

Examples:

```
$ omabox keys --wait super+space
$ omabox keys -t 'hello wörld' Return
$ omabox keys --pass PASSWORD Return
```

```
omabox keys [-b NAME] [--window SEL] [--wait] (COMBO | -t TEXT | --pass VAR | -s DURATION | down:KEY | up:KEY)...  e.g. super+space  -t hi  Return
```

`omabox help keys` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--strict] [--json]        [--expect tree TEXT] [--tree] (not run's)        after it, a change on screen within --start, then still for --quiet; 124 if not by --timeout;        the line adds what changed on the desktop (windows, layers, focus), a 124 where the input went

`run` starts the command with the box's environment, not yours: --pass VAR hands it one of your variables (a password too: never on a command line); --env-file FILE hands it a file's KEY=VAL lines (a dev.env: read as data, nothing expanded; --pass wins); `keys --pass VAR` types one (never `-t` for a secret: the process list shows it). `keys -t` and `keys --pass` type newline and tab (Return, Tab); any other control character is refused (exit 2); a value's one trailing \r is dropped. --env KEY=VAL is the box session's, on `up` (and a throwaway `run`'s box); `run --env` on a box that is up hands it to the command, as --env-file does (--pass wins). Never what the session sets itself (PATH, HOME, XDG_RUNTIME_DIR, XDG_*_HOME, WAYLAND_DISPLAY, DISPLAY, HYPRLAND_INSTANCE_SIGNATURE, LD_PRELOAD, OMABOX_BOX...), by any of them.

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`keys --window` focuses the window (the active one again), then types; while a layer holds the keyboard against any window (Omarchy's launcher, a menu) it refuses, exit 1, before sending or focusing anything: close the layer first (Escape; twice in a launcher with text in its field). `keys down:KEY` presses KEY and leaves it down across later commands (`pointer move`, `click`, `keys`) until `keys up:KEY`: a bind on a key's release, a gesture made while a key is held. KEY is one key (XF86Tools, super, shift, a; down:A holds a). Hyprland joins it with the other keys: `keys down:super`, then `keys a` fires SUPER+A; shift held types capitals. A held letter repeats in the focused app, as a real key does, until another key is pressed. A key already held, or an up:KEY not held, is exit 1, before any key of the call is sent. Anything still held is let go when the box goes down (with your agent, for a box named after your session); a holder killed outright, by the next keys (said). Not with --pass.

`keys -s DURATION` and `pointer -- sleep DURATION` pause there (300ms, 1.5s; up to 10m). A bare number there is refused (milliseconds up to 0.9, seconds everywhere else): write the unit.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

#### omabox click

Click in screen, window or screenshot coordinates. `--steps` travels there, hovering what it crosses; `--mod` holds ctrl, shift or alt.

Examples:

```
$ omabox click --window myapp 40 12
$ omabox click --steps 20 --mod ctrl 960 540
```

```
omabox click [-b NAME] [--window SEL [--no-raise] | --in SHOT] [--wait] (X Y | --cell C3) [BTN] [--double]
             [--steps N | --glide DURATION] [--mod MODS]  --steps: travel there; --glide: in that time; --mod ctrl: ctrl-click
omabox click [-b NAME] [--window SEL | --layer SEL] --find TEXT [--index N] [BTN] [OPTIONS as above]
                                                       what the accessibility tree names TEXT, at its middle
omabox click [-b NAME] [--window SEL] --image FILE [--similar 0.95] [--offset DX,DY] [--index N] [BTN] [OPTIONS as above]
                                                       where an image is (find --image), at its middle
```

`omabox help click` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--strict] [--json]        [--expect tree TEXT] [--tree] (not run's)        after it, a change on screen within --start, then still for --quiet; 124 if not by --timeout;        the line adds what changed on the desktop (windows, layers, focus), a 124 where the input went

--layer SEL (or -l SEL): a layer surface (the bar, a panel, a menu): its namespace, address:0x... or pid:N

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

--fit N scales a shot's image down to N pixels on its longest side (a scaled screen's image is its layout times the scale: 2560 px for a 1280 px layout at 2). --zoom N (2-16, with -g) shows each pixel of a small crop as N x N, unblended: a 1 px border, a glyph's edge; `click --in` maps it back. -g "X,Y WxH" (or X,Y,W,H) crops: the screen's, or with --window the window's own coordinates; a region past the edge is cut to it, said on stderr (one with nothing inside is refused). At a fractional scale the image is the screen's own pixels from the one its start rounds to (30 at 1.25 is 37.5 px: from 38), not grim's blend, so find --image finds a crop where it was cut; the region recorded (stderr, --json, click --in) is the one asked. A cropped or scaled shot says so on stderr: `click --in SHOT X Y` (and `drag`, `pointer --in`) take that image's pixels (a window shot follows the window if it moved). Screen shots show the pointer (--no-pointer: not this one; `pointer hide`: none until `pointer show`); window shots never do. -o makes the file's folder if it is missing. An action `--in` a screen shot (click, scroll, drag, pointer) is refused, exit 1, when what is at its point is not what was there at the shot: another window or layer over it, or the window moved under it ("the screen changed at X,Y since SHOT: then on ..., now on ...; take a new shot"). A change elsewhere on the screen (a toast, a clock, a window away from the point) is not. One Hyprland read per point; a --burst frame is not checked.

`shot --grid N` (2-26) draws N lettered columns (A, B, ...) and N numbered rows over the shot (of the screen, -g, --monitor or a window), the labels in a 28 px margin top and left so nothing is hidden; stderr names each column's and row's span in the shot's coordinates. For a small target with no tree: `--grid N --cell C3` is that cell cropped as -g would, enlarged (--zoom, to about shot-fit's size, 1000 px without; --fit N or --zoom N to choose) and gridded again, its stderr saying the -g for a closer look still; a target a grid line cuts is both cells, `--cell C3:D3` (any rectangle of cells). `click --in GRID.png --cell C3` clicks the cell's middle; `click --in GRID.png X Y` takes the image's pixels, margin included (a point in it is refused). A grid shot is never what --changed compares with, nor a --since (shot --changed, wait change). Needs ImageMagick's magick.

The pointer starts at the screen's centre and stays where it was left; `click` and `pointer move` jump there. --steps N travels in N steps from where it is, over what lies between: under Omarchy's focus-follows-mouse the windows on the way take focus, as with a real mouse (`pointer --steps N -- move A move B` passes through A). --mod MODS (ctrl, shift, alt, super, altgr; ctrl+shift, or --mod again) holds modifiers down across a click, drag, scroll or pointer run, released after it, whatever happens to omabox. SUPER with the left or right button is Hyprland's move or resize window, not the app's. --glide DURATION (up to 10s; for videos) travels there in that time, eased in and out, a step each 40 ms: the pointer seen moving, as a hand moves it (drag: to its start, then its path, each in that time). Without it nothing glides, but while `record start --glide` records.

BTN is left (the default), right, middle, back or forward (also side and extra: a mouse's thumb buttons, BTN_SIDE and BTN_EXTRA, which apps take as back and forward).

`click --find TEXT` clicks the node of the accessibility tree `tree` reads (--window SEL, none: the active window; --layer SEL (or -l SEL) a layer's) named TEXT, with the real pointer at the middle of what of it is in view, read again on every call. TEXT matches a name in any case: an exact name wins over a part of one, and a control over a label of its name. Several in view: exit 2, their lines numbered with their ancestors, and --index N clicks that one. Exit 1, nothing clicked: nothing is named TEXT, or the one named so is hidden (it or what it is in is not showing), has no bounds, is out of view (outside its window or a container's bounds: scroll it into view first) or disabled, said which. Its line and where the pointer went are said on stderr; BTN, --double, --mod, --steps, --glide and --wait as with X Y.

`find --image FILE` finds a picture where there is no accessibility tree (the shell, its plugins, the bar, a terminal): FILE is a PNG, best a crop of a shot of the box (`shot -g "X,Y WxH" -o FILE`), whose comment records the scale it was taken at. Each match is a line `X,Y WxH SCORE` in the layout's coordinates, in reading order (`-g`'s, click's, shot -g's), 1 the same pixels; exit 1 none, with the best score seen and where. Several: all listed (20, --all every one) and said on stderr, never one taken for you. --similar (0.95) is the score a match needs: normalised correlation of the colours, less for another contrast or tone (a grey switch is not its blue self); an image of one colour by its difference, transparent pixels not compared. A box drawn at another scale than FILE's resizes it and says so, then needs 0.8 unless --similar says; its one match with another place within 0.05 of it is a near tie (a look-alike scores that close once scaled), said on stderr and as --json's near_tie. -g looks in a region, --window SEL in that window's own pixels (covered or not). `click --image FILE` clicks the middle of the one match (--offset DX,DY beside it: a label's field), several exit 2 numbered for --index N, a near tie exit 2 with both (a crop shot in this box tells them apart); `wait image FILE [--gone]` polls for it, a near tie not counted as there (0, 124, 1 as the other waits). Each takes a frame and searches it in about 50-100 ms. A jailed agent's FILE is read by its own omabox.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

#### omabox drag

Press, move, hold, release: sliders, selections, drag and drop.

Examples:

```
$ omabox drag --window myapp 10 10 200 80
```

```
omabox drag [-b NAME] [--window SEL [--no-raise] | --in SHOT] [--wait | --shot FILE] X1 Y1 X2 Y2 [BTN]
            [--steps 10 | --glide DURATION] [--hold DURATION] [--mod MODS]  press, move, hold, release
            [--shot-fit N | --shot-g "X,Y WxH" | --shot-monitor NAME]   (with --shot: as shot's --fit, -g, --monitor)
```

`omabox help drag` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--strict] [--json]        [--expect tree TEXT] [--tree] (not run's)        after it, a change on screen within --start, then still for --quiet; 124 if not by --timeout;        the line adds what changed on the desktop (windows, layers, focus), a 124 where the input went

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

--fit N scales a shot's image down to N pixels on its longest side (a scaled screen's image is its layout times the scale: 2560 px for a 1280 px layout at 2). --zoom N (2-16, with -g) shows each pixel of a small crop as N x N, unblended: a 1 px border, a glyph's edge; `click --in` maps it back. -g "X,Y WxH" (or X,Y,W,H) crops: the screen's, or with --window the window's own coordinates; a region past the edge is cut to it, said on stderr (one with nothing inside is refused). At a fractional scale the image is the screen's own pixels from the one its start rounds to (30 at 1.25 is 37.5 px: from 38), not grim's blend, so find --image finds a crop where it was cut; the region recorded (stderr, --json, click --in) is the one asked. A cropped or scaled shot says so on stderr: `click --in SHOT X Y` (and `drag`, `pointer --in`) take that image's pixels (a window shot follows the window if it moved). Screen shots show the pointer (--no-pointer: not this one; `pointer hide`: none until `pointer show`); window shots never do. -o makes the file's folder if it is missing. An action `--in` a screen shot (click, scroll, drag, pointer) is refused, exit 1, when what is at its point is not what was there at the shot: another window or layer over it, or the window moved under it ("the screen changed at X,Y since SHOT: then on ..., now on ...; take a new shot"). A change elsewhere on the screen (a toast, a clock, a window away from the point) is not. One Hyprland read per point; a --burst frame is not checked.

`omabox config shot-fit N` makes --fit N every shot's default ($OMABOX_SHOT_FIT overrides it; off or `default` clears it): for a model that reads points in the smaller image its API scales a big one down to (1456 for 16:9 on Claude), set once. It goes wherever --fit goes (a window, -g, --monitor, --burst, drag --shot), not --changed or --zoom; --fit N wins, --fit 0 is full size.

The pointer starts at the screen's centre and stays where it was left; `click` and `pointer move` jump there. --steps N travels in N steps from where it is, over what lies between: under Omarchy's focus-follows-mouse the windows on the way take focus, as with a real mouse (`pointer --steps N -- move A move B` passes through A). --mod MODS (ctrl, shift, alt, super, altgr; ctrl+shift, or --mod again) holds modifiers down across a click, drag, scroll or pointer run, released after it, whatever happens to omabox. SUPER with the left or right button is Hyprland's move or resize window, not the app's. --glide DURATION (up to 10s; for videos) travels there in that time, eased in and out, a step each 40 ms: the pointer seen moving, as a hand moves it (drag: to its start, then its path, each in that time). Without it nothing glides, but while `record start --glide` records.

BTN is left (the default), right, middle, back or forward (also side and extra: a mouse's thumb buttons, BTN_SIDE and BTN_EXTRA, which apps take as back and forward).

`drag` presses at X1 Y1, moves to X2 Y2 in --steps (10), holds there for --hold (a drop target reacting to the hover) and releases. --hold takes a duration up to 60s, like 300ms or 2s: a bare number is seconds, as for every duration. A toolkit's drag-and-drop (GTK, Chromium, Qt) starts and drops at X2 Y2: the path takes 150 ms at least, and ends with a 1 px nudge and back. --shot FILE takes a shot while the button is still down, as `shot` takes one: the whole layout (--shot-fit N, --shot-g "X,Y WxH" and --shot-monitor NAME are shot's --fit, -g and --monitor; a scaled or cropped one says so, for `click --in`). --wait ignores the cursor along the drag's path (it is in every frame): what the drag changes beside it counts, a change wholly under it may not.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

#### omabox scroll

Scroll there, up, down or sideways, as a mouse wheel's notches or a touchpad's smooth scroll; `--mod super` for Omarchy's SUPER+wheel binds.

Examples:

```
$ omabox scroll 960 540 30
$ omabox scroll --window myapp 200 100 0 60 --source finger
```

```
omabox scroll [-b NAME] [--window SEL [--no-raise] | --in SHOT] [--wait] X Y DY [DX] [--source wheel|finger|continuous|tilt]
              [--mod MODS]
                                                       scroll there (DX: sideways; 15 is a wheel notch)
```

`omabox help scroll` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

--wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--strict] [--json]        [--expect tree TEXT] [--tree] (not run's)        after it, a change on screen within --start, then still for --quiet; 124 if not by --timeout;        the line adds what changed on the desktop (windows, layers, focus), a 124 where the input went

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`scroll X Y DY [DX]` moves the pointer there and scrolls: DY down (negative: up), DX right (negative: left), in wl_pointer units (15 is one wheel notch). Without --source it is one plain axis event; --source wheel (or tilt) sends a notch a frame, as a mouse does (apps counting notches see each), finger or continuous the distance in 10 frames then a stop, as a touchpad does (kinetic scrolling). A wheel turns in whole notches: DY 20 scrolls 15, said on stderr. Hyprland binds see a wheel as mouse_up/mouse_down and mouse_left/mouse_right (--mod super: Omarchy's SUPER+wheel binds); a tilt or a finger reaches apps but no bind (Hyprland binds the wheel source only): test binds with a wheel. Qt apps get every wheel, a real mouse's too, from a device of type TouchPad (Qt's Wayland plugin has no other: QTBUG-112432), so a Qt Quick WheelHandler left at its default acceptedDevices (Mouse) never fires; a wheel still is one (angleDelta 120 a notch; pixelDelta 15 from Qt 6.12). Give it `acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad`, or use a MouseArea's onWheel.

The pointer starts at the screen's centre and stays where it was left; `click` and `pointer move` jump there. --steps N travels in N steps from where it is, over what lies between: under Omarchy's focus-follows-mouse the windows on the way take focus, as with a real mouse (`pointer --steps N -- move A move B` passes through A). --mod MODS (ctrl, shift, alt, super, altgr; ctrl+shift, or --mod again) holds modifiers down across a click, drag, scroll or pointer run, released after it, whatever happens to omabox. SUPER with the left or right button is Hyprland's move or resize window, not the app's. --glide DURATION (up to 10s; for videos) travels there in that time, eased in and out, a step each 40 ms: the pointer seen moving, as a hand moves it (drag: to its start, then its path, each in that time). Without it nothing glides, but while `record start --glide` records.

`wait still`: nothing on screen changed for --quiet; a caret blinking in place (4 px thin, 40 long at most), the cursor and a blinker do not count, and are said (--strict counts them). A blinker is a spot 48 px a side at most that came back to how it looked 3 times (a dot blinking or pulsing, a looping spinner): from then on it is left out, said on stderr, and learnt again where it moves; a counter or a progress bar never comes back, so it counts. `wait change`: the first change there, for an app that redraws later, by itself (a sync, a timer): then `wait still`; never `wait until -- false` (nor `-- true`) as a sleep: `wait log` for a line, `wait for 2s` for a time that really is fixed. `wait change --since SHOT`: changed since that shot, at once if it already differs (a redraw done before the wait started: after an edit or an IPC call), else the first change; `wait still --like SHOT`: until it looks like SHOT again (a new frame every 200 ms). SHOT is a full-size shot of this box: the screen's (-g: a part of it), a crop of it, or a whole window's (that window, wherever it is; --ignore in its coordinates). The pointer, a caret alone and --ignore's regions are no difference (--strict counts a caret); a clock in the region is one: --ignore it. `keys`, `click`, `scroll`, `drag` and `run -d` take --wait [--start 2s] [--quiet 300ms] [--timeout 10s] [-g GEOM] [--ignore GEOM]... [--json]: a change within --start (5s for run -d), then quiet. --ignore "X,Y WxH" (up to 16) leaves out an animation that never stops (a spinner, a glow); a 124 "still changing" names it when one small region kept changing. -g watches only that part of the screen. The screen is every monitor; -g and --ignore are in the layout's coordinates (as a plain click's), and beside --window in the window's own (0,0 its top left corner), as --window's X Y and shot -g are. To watch a part of the screen whatever the window, -g without --window. Their line then adds what changed on the desktop since just before the input: a window opened or closed, a layer drawn or hidden, focus, a title, the workspace (3 at most, then "+N more (omabox events --since OFFSET)"); a 124 says where the input went (the focused window, a layer holding the keyboard, what was under the point) and "no window, layer or focus changed" when nothing did. Since the input, not caused by it. --json adds changes (null: not read), target and events_since; run -d's adds job (its pid, then not printed on a line of its own). `keys`, `click`, `scroll` and `drag` --wait take --expect tree TEXT (#319): once the screen settled, the tree holds TEXT, read as `wait tree TEXT` reads it, in the window the input went to (--window's, click --find's or its layer's; none: the active one) until --timeout (from the input), once at least: `click --find Save --wait --expect tree 'label "Saved"' && keys ...` stops at a 124 when it does not, the line then saying what the tree had instead; the line adds the line holding it, --json `expect` {tree, met, detail}. The input was sent all the same. --tree (#288) reads that window's tree (none given: the one under a click's point, else the active one) before the input and again once the screen settled, and the line adds what changed in it ("no change in the app's tree", else "the app's tree: N changes" and a line each under it, 20 at most: `entry "Name": '' → 'hello'`, `check box "Beta": +checked -unchecked`, `label "Idle" → "Saving"`, `+ dialog "Confirm" (and 3 inside)`); a password field's text, and any text after keys --pass, never shown; --json adds tree {window, changes, why}. Opt-in: a read before the input (the box's first turns accessibility on, ~3 s). No tree (a terminal): "no tree to compare (why)", the input sent. Exit 0 satisfied, 124 not by --timeout (after --wait: the input WAS sent), 1 unknown (the box went down, an interactive box's hidden window renders nothing): never 0 for what could not be seen. Durations, here as everywhere: 300ms, 2s, 1.5m, 1h (a bare number is seconds); --timeout at most 10m. Waiting counts as using the box.

#### omabox pointer

Raw pointer moves, button presses, scrolls and pauses, for what `click` and `drag` don't cover.

Examples:

```
$ omabox pointer --steps 10 -- move 400 300 scroll 3
```

```
omabox pointer [-b NAME] [--window SEL | --in SHOT] [--steps N | --glide DURATION] [--mod MODS] -- ARGS...
               raw: move X Y [--steps N], click/down/up [BTN], scroll DY, hscroll DX,
               source wheel|finger|continuous|tilt, sleep DURATION
omabox pointer [-b NAME] hide | show                   the pointer out of shots and recordings (it still moves), over reloads
```

`omabox help pointer` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`keys -s DURATION` and `pointer -- sleep DURATION` pause there (300ms, 1.5s; up to 10m). A bare number there is refused (milliseconds up to 0.9, seconds everywhere else): write the unit.

--fit N scales a shot's image down to N pixels on its longest side (a scaled screen's image is its layout times the scale: 2560 px for a 1280 px layout at 2). --zoom N (2-16, with -g) shows each pixel of a small crop as N x N, unblended: a 1 px border, a glyph's edge; `click --in` maps it back. -g "X,Y WxH" (or X,Y,W,H) crops: the screen's, or with --window the window's own coordinates; a region past the edge is cut to it, said on stderr (one with nothing inside is refused). At a fractional scale the image is the screen's own pixels from the one its start rounds to (30 at 1.25 is 37.5 px: from 38), not grim's blend, so find --image finds a crop where it was cut; the region recorded (stderr, --json, click --in) is the one asked. A cropped or scaled shot says so on stderr: `click --in SHOT X Y` (and `drag`, `pointer --in`) take that image's pixels (a window shot follows the window if it moved). Screen shots show the pointer (--no-pointer: not this one; `pointer hide`: none until `pointer show`); window shots never do. -o makes the file's folder if it is missing. An action `--in` a screen shot (click, scroll, drag, pointer) is refused, exit 1, when what is at its point is not what was there at the shot: another window or layer over it, or the window moved under it ("the screen changed at X,Y since SHOT: then on ..., now on ...; take a new shot"). A change elsewhere on the screen (a toast, a clock, a window away from the point) is not. One Hyprland read per point; a --burst frame is not checked.

`scroll X Y DY [DX]` moves the pointer there and scrolls: DY down (negative: up), DX right (negative: left), in wl_pointer units (15 is one wheel notch). Without --source it is one plain axis event; --source wheel (or tilt) sends a notch a frame, as a mouse does (apps counting notches see each), finger or continuous the distance in 10 frames then a stop, as a touchpad does (kinetic scrolling). A wheel turns in whole notches: DY 20 scrolls 15, said on stderr. Hyprland binds see a wheel as mouse_up/mouse_down and mouse_left/mouse_right (--mod super: Omarchy's SUPER+wheel binds); a tilt or a finger reaches apps but no bind (Hyprland binds the wheel source only): test binds with a wheel. Qt apps get every wheel, a real mouse's too, from a device of type TouchPad (Qt's Wayland plugin has no other: QTBUG-112432), so a Qt Quick WheelHandler left at its default acceptedDevices (Mouse) never fires; a wheel still is one (angleDelta 120 a notch; pixelDelta 15 from Qt 6.12). Give it `acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad`, or use a MouseArea's onWheel.

The pointer starts at the screen's centre and stays where it was left; `click` and `pointer move` jump there. --steps N travels in N steps from where it is, over what lies between: under Omarchy's focus-follows-mouse the windows on the way take focus, as with a real mouse (`pointer --steps N -- move A move B` passes through A). --mod MODS (ctrl, shift, alt, super, altgr; ctrl+shift, or --mod again) holds modifiers down across a click, drag, scroll or pointer run, released after it, whatever happens to omabox. SUPER with the left or right button is Hyprland's move or resize window, not the app's. --glide DURATION (up to 10s; for videos) travels there in that time, eased in and out, a step each 40 ms: the pointer seen moving, as a hand moves it (drag: to its start, then its path, each in that time). Without it nothing glides, but while `record start --glide` records.

BTN is left (the default), right, middle, back or forward (also side and extra: a mouse's thumb buttons, BTN_SIDE and BTN_EXTRA, which apps take as back and forward).

`shot --no-pointer` (a screen shot, --burst too) and `record --no-pointer` leave the pointer out, for stills and videos meant for people (no arrow on the app, none parked on a hover state): it is hidden (Hyprland's cursor:invisible), a frame without it awaited (up to a second), and shown again after, as it was, also on a failure or Ctrl-C; a recording keeps it hidden until `record stop`. `pointer hide` (or `up --no-pointer`) hides it in the box until `pointer show`, over config reloads and theme switches (omarchy-theme-set reloads). Hidden, it still moves and clicks where it is told, focus still follows it, and peek's marks still show it; `wait` and `--changed` leave out where it is, as they do when it shows.

### The box's Hyprland and shell

#### omabox hyprctl

The box's Hyprland, never yours.

Examples:

```
$ omabox hyprctl -j clients
```

```
omabox hyprctl [-b NAME] ARGS...
```

`omabox help hyprctl` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

A box's Hyprland runs a Lua config: `hyprctl dispatch` takes a Lua dispatcher (dispatch 'hl.dsp.window.close()'). The old syntax (dispatch fullscreen 0) dispatches nothing: hyprctl fails it (1 for a --batch, where hyprctl says 0) and prints the `omabox lua 'hl.dispatch(…)'` for it. A Lua dispatch Hyprland refuses (no such window) is exit 1 too, its answer as it came: hyprctl's `warning: …`, lua's {"ok":false,…} (only what hl.dispatch returned, not a table of yours).

#### omabox lua

Lua in the box's Hyprland, printing what it returns (tables as JSON).

Examples:

```
$ omabox lua 'hl.get_active_window()'
```

```
omabox lua [-b NAME] [--json] (EXPR | -)               Lua in the box's Hyprland, printing what it returns
```

`omabox help lua` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`lua` takes an expression or statements (`return` what to print); one line per value: strings and numbers as they are, nil as nil, tables and Hyprland's objects (a window, a monitor) as JSON (--json: strings quoted too). A Lua error is exit 1 with its message. An error inside a callback (hl.on, hl.timer) that runs later is logged nowhere: catch it with pcall.

A box's Hyprland runs a Lua config: `hyprctl dispatch` takes a Lua dispatcher (dispatch 'hl.dsp.window.close()'). The old syntax (dispatch fullscreen 0) dispatches nothing: hyprctl fails it (1 for a --batch, where hyprctl says 0) and prints the `omabox lua 'hl.dispatch(…)'` for it. A Lua dispatch Hyprland refuses (no such window) is exit 1 too, its answer as it came: hyprctl's `warning: …`, lua's {"ok":false,…} (only what hl.dispatch returned, not a table of yours).

#### omabox restart-shell

Reload the box's Omarchy shell after you edit a plugin; it says why a plugin did not load.

Examples:

```
$ omabox restart-shell
```

```
omabox restart-shell [-b NAME]                         reload the Omarchy shell (after plugin edits)
```

`omabox help restart-shell` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--plugin PATH|ID: a shell plugin, read-only, enabled where its manifest says; `up` and `restart-shell` warn when Omarchy's validator or the shell refuses it (`ls --json`: plugin_status). One the box has at its own path (in the repo `up` runs from, a same-path --ro-bind or an --overlay) is linked to there, as on a desk, so readlink -f leads into its repo; any other is mounted (plugin_status: via).

`plugin add PATH|ID` puts a plugin in a box that is up as --plugin would have: read-only, linked to where the box has it at its own path or mounted, made known to the shell (a rescan, until it lists it) and enabled, its state said (`ls --json`: plugin_status). `plugin remove ID` takes one out (one from up's --plugin too): disabled, unmounted or unlinked, rescanned. A link made by hand in the box HOME works only for a folder the box has at its own path, and `omarchy plugin enable` right after `rescanPlugins` says "is not known" until the rescan is done; `plugin add` does both. Not inside ai-jail, nor on a box a jail started (up --plugin there).

--desk-shell: your desktop's shell as it is, to check a plugin against a real desk: every plugin in ~/.config/omarchy/plugins (read-only, as --plugin's; a --plugin of the same id wins: your working copy) but omabox's own widget (it lists your boxes; --plugin mounts it), your shell.json unfiltered (only idle held off: a box has no real input; omabox's widget taken out of it), and the other files in ~/.config/omarchy your plugins read (a plugin's JSON, a folder beside shell.json) copied into the box's. Never api-keys.env nor anything named or holding a key, token, secret, password, credential, auth, cookie or session (any .env, .pem, .gpg...), hooks/ (your scripts), a git dir or a backup; regular files up to 1 MiB (16 MiB, 1000 in all); a link only to a file inside the folder. `up` says what went in and what did not, and why (`ls --json`: desk_shell). Not with --stock-bar or --stock; not inside ai-jail.

### You and your desktop

#### omabox peek

A live, view-only window of any box on workspace 9, opened without taking your focus.

Examples:

```
$ omabox peek -b app-tray-5cc72cdc
```

```
omabox peek [-b NAME] [--monitor NAME] [--fps N] [--focus] [--workspace WS]  live view-only window of a box (workspace 9)
```

`omabox help peek` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Interactive boxes and peek windows open on workspace 9, without focus: `omabox config workspace WS` (1-99; special:omabox, a special workspace of omabox's own: the bar widget's Show opens it, a workspace switch hides it; special:NAME; special = Omarchy's scratchpad on SUPER+S, on 4.5 its Quake console) or --workspace. A peek window shows click, pointer and keys for ~3 s (a ring, key captions, --pass values as *); never the box's own frames.

More monitors: `up --monitor SPEC` (repeatable) or `monitor add SPEC` on a running box. SPEC is WxH[@HZ][,scale=S][,right|below|X,Y]: placed right of the last one made by default, or below it, or at X,Y in the layout (which starts at 0,0 on the main screen: no left or above). Scale 1 to 4; Hyprland may round it to a whole-pixel size (2560x1440 at 1.5 becomes 1.6). The main screen (--size, `mode`) is HEADLESS-2; the others HEADLESS-3, -4, ... (or --name); on NVIDIA, where a box draws on Wayland outputs, WAYLAND-1 and WAYLAND-2, -3, ... (no --name); there a headless output a program makes itself (`hyprctl output create headless`) is listed 0x0, which `monitor list` and `shot` say, naming a box on another GPU to test it in. `monitor remove NAME` unplugs one: Hyprland moves its workspaces to the others. They survive a config reload, and one placed right or below moves when the one before it changes size (`mode`, said) or goes; an X,Y one stays. Coordinates (click, drag, pointer, pixel, -g) are the layout's (`pixel` refuses a point in a gap between them); `shot --monitor NAME` takes one monitor (a shot of a mixed-scale layout comes out at the highest scale: --fit). `peek` shows the main screen, `peek --monitor NAME` another: a window per monitor, tiled on the workspace, each marking the clicks and pointer on its own monitor (keys on all); one whose monitor drops (`output drop`) says it is gone, and shows it again once it is back; the whole layout at once is `shot`. An interactive box's monitors are windows on your desktop, on its workspace, placed in the box as a headless box's; on your screen the box's layout scaled as a whole, as display settings draw it: one scale for every window (at most 1), the picture centred on the monitor its main window is on, the main window floated for it (it tiles again when the last monitor goes); each `monitor add` and `remove` lays it out again. Each window is a view of its monitor: the monitor's size in the layout, which the bar and apps see, is the one asked for (the main screen's --size, a SPEC's), its mode its window's pixels at a scale of at most 1 (`monitor list`). Resizing a window changes its view's scale, not the monitor (a window of another shape shows it smaller along one side); closing one unplugs it. They need aquamarine's fix, as NVIDIA boxes do, and omabox's build of it puts your pointer on the monitor whose window it is in and keeps your cursor shown from one window to the next (`monitor add` says when a box's aquamarine does neither).

#### omabox keys-to-box

For an interactive box: SUPER keys go to it while its window has focus and the pointer is over it.

Examples:

```
$ omabox keys-to-box -b box-1 on
```

```
omabox keys-to-box [-b NAME] [on|off]                  interactive: SUPER keys to the box while focused, pointer on it
```

`omabox help keys-to-box` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

SUPER + ALT + ESCAPE toggles sending SUPER keys to an interactive box, once: until focus leaves it, or a key is pressed with the pointer off it. `keys-to-box on` makes them follow focus and the pointer, for the box's lifetime: its window has focus and the pointer is over it, SUPER is the box's; focus goes elsewhere or the pointer leaves it (your bar, another monitor), it is yours, and the pointer back over it gives it to the box again. SUPER + ALT + ESCAPE over the box gives the keys back until the box loses focus and gets it again. No argument prints on or off. While keys go to a box, its window's border takes the theme's red and the bar widget's icon is lit.

#### omabox clip

Your clipboard into an interactive box, once, or the box's back to you. Never for agents.

Examples:

```
$ omabox clip
$ omabox clip --from-box
```

```
omabox clip [-b NAME] [--from-box]                     your clipboard into an interactive box, or back
```

`omabox help clip` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`clip` hands your clipboard's item (text, else an image by its type) to an interactive box, once; --from-box hands the box's back. With no -b: the interactive box whose window has focus, else the only one. Never for agents (refused in their sessions, under the guard, in ai-jail). Nothing keeps watching either clipboard. Bind it to a key in your Hyprland config to paste into the box you are in.

#### omabox env

Exports that point Wayland tools on your side at a box, so their windows open in it.

Examples:

```
$ eval "$(omabox env)"
```

```
omabox env [NAME | -b NAME]                            exports for host-side Wayland tools
```

`omabox help env` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

#### omabox ports

Every box's servers, and who has each port on your `127.0.0.1`: that box, another box, one of your own processes, or nothing yet. When a dev server says the address is in use, this names who has it.

Examples:

```
$ omabox ports
$ omabox ports --json
```

```
omabox ports [-b NAME] [--json]                        boxes' TCP servers, and which of them your 127.0.0.1 reaches
```

`omabox help ports` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

Every box has its own network (pasta): by default the internet, the LAN and your servers. Across the box boundary use 127.0.0.1, not localhost; a box's servers appear on your 127.0.0.1 about a second after they listen, one box per port (a box server on a port the host or another box has fails to start, address in use; of two started within a second, only one gets it there: `omabox ports` names the holders). --net isolated: a loopback and the --allow ports only, which are for reaching those host ports from the box: pasta listens on each in the box, so a box server on one fails, address in use (`ports`: allowed); serve on another; --addr ADDR (repeatable) puts an address on that loopback, for an app that wants a peer from a non-local address: one in a documentation range (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32). A server on 203.0.113.10 sees a client bound to 203.0.113.11 come from there. --net host (asked for by name only; no config picks it): your host's network itself, no pasta, for a tool that scans the real LAN. The box keeps its own seat, session bus, runtime dir and HOME, but its servers take your host's real ports (they collide with your services and other host boxes; nothing is forwarded, `ports`: host-net), it sees your real interfaces and its ARP and ICMP reach your LAN. Not for code you do not trust. Refused with --allow, --addr, --xwayland (its X server would be your host's), --desktop desk, inside ai-jail, and while protect-ports names a port.

ON 127.0.0.1:PORT HERE, by its --json host.state: this (this box); this-resets (this box's pasta holds it, but the server is on ::1 or a 127.x other than 127.0.0.1 only, so connections are reset); shared (several boxes serve on it and one of them holds it, which cannot be read; one on ::1 only is named as resetting); host (a process of yours, named; from inside ai-jail, unnamed, and also a box outside the jail serving on it too); other-user; nothing (yet: a port comes about a second after its server listens); isolated, no-network (the box's net: nothing is forwarded); allowed (an isolated box's --allow port: pasta's in the box, leading to the host's); host-net (a --net host box's server, on the host's own port: nothing forwarded).

#### omabox which

The box a process on your machine is in. A box's bar has your bar's command line, so `pgrep quickshell` can look like two desktop shells.

Examples:

```
$ omabox which 12345
```

```
omabox which [--json] PID                              the box a host process is in, or "not in a box" (exit 1)
```

`omabox help which` adds:

A box's processes look like the desktop's in a host process list (its shell has the same command line): `omabox which PID` names the box a host pid is in, by its pid namespace or an ancestor's, else by OMABOX_BOX, which every process a box's session starts carries (said so); `not in a box`, exit 1, for anything else, another user's processes too (boxes run as you); exit 2 for a pid that is gone.

`omabox pid`, `which` the other way round: the host PID of the box's Hyprland (the default) or its shell, for /proc/PID/maps, perf or strace on the host; --in-box the PID as the box numbers it (`gdb --pid`, `omabox run -- kill`). --json: {box, process, pid, box_pid}. Nothing on stdout and exit 1 when it is not running.

#### omabox calibrate

Does this model need `--fit` to click right? A test card it reads, then the answer.

Examples:

```
$ omabox calibrate
```

```
omabox calibrate [-b NAME] [--size WxH] [CARD]        a test card to read as a shot: do your clicks need --fit?
omabox calibrate [CARD] --answer "A X,Y B X,Y ..." [--json]   where you see each mark: 1:1, or the --fit N that maps it
```

`omabox help calibrate` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

-o (or --output) names what the command writes.

A harness may show its model a big image scaled down, and some models then give points in the smaller image: `click X Y` off a full-size shot lands short, up and to the left, and nothing says so. `calibrate` draws a test card (here, no box needed: the size of a full shot of the box, or 1920x1080 with none up), 6 marks at random points, A to F, and prints its path and how to answer: open it as you open a shot and give each cross's centre in the image's pixels. --answer says whether they read 1:1 (full-size shots and `click X Y` land), else at what scale, the --fit N whose shots, with `click --in`, map them back within a few pixels, and the `omabox config shot-fit N` to suggest to the user (their setting: never set it). Readings no one scale fits (a mark misread, two letters swapped) are said so, exit 1: draw a new card and read again. --answer reads the card the last `calibrate` here drew (one per session or repo), or CARD.

#### omabox host

One command on your real desktop, when you asked for it: the one way past the guard, on the record.

Examples:

```
$ omabox host -- hyprctl reload
```

```
omabox host -- CMD [ARG...]                            one command on your real desktop (when asked for)
```

`omabox help host` adds:

The agent guard (opt-in) gives agents' shell commands (Claude Code, Codex) a display that does not exist, so a window, hyprctl or grim outside a box fails instead of reaching your desktop; omabox still works, and `omabox host` runs a command you asked for on the real desktop.

#### omabox config

Your settings: where windows open, confirm before closing, the bar icon, the GPU headless boxes render on.

Examples:

```
$ omabox config
$ omabox config workspace special
$ omabox config gpu
```

```
omabox config [--json | KEY [VALUE | default]]         settings: workspace, confirm-close, bar-icon, gpu, shot-fit, protect-ports, desktop
```

`omabox help config` adds:

`omabox config shot-fit N` makes --fit N every shot's default ($OMABOX_SHOT_FIT overrides it; off or `default` clears it): for a model that reads points in the smaller image its API scales a big one down to (1456 for 16:9 on Claude), set once. It goes wherever --fit goes (a window, -g, --monitor, --burst, drag --shot), not --changed or --zoom; --fit N wins, --fit 0 is full size.

Interactive boxes and peek windows open on workspace 9, without focus: `omabox config workspace WS` (1-99; special:omabox, a special workspace of omabox's own: the bar widget's Show opens it, a workspace switch hides it; special:NAME; special = Omarchy's scratchpad on SUPER+S, on 4.5 its Quake console) or --workspace. A peek window shows click, pointer and keys for ~3 s (a ring, key captions, --pass values as *); never the box's own frames.

Closing an interactive box's window ends the box; `omabox config confirm-close on` asks first (a second close is a yes). A headless box renders on the first GPU; `omabox config gpu` lists them, and `omabox config gpu nvidia` (amd, intel, a driver's name, or a PCI slot: two GPUs of one kind) picks another; `up` falls back to the first, saying so and why, when that one is not there (a card handed to a VM). The first is one that renders: a VM's virtio-gpu without virgl (software only) comes after any other, and when it is the only one `up` refuses it before starting a box that would die there. $OMABOX_RENDER_NODE overrides it. An interactive box renders on the GPU your desktop's compositor uses, whatever the setting. `omabox config protect-ports 8080,5432` keeps those host ports from every connected box, through any of the host's addresses (an isolated box's --allow refuses them; `default` removes them; it needs nft). `omabox config desktop plain` (or omarchy) is the desktop of a box up gets without --desktop; auto, the default, is Omarchy's where Omarchy is installed and plain where it is not.

### Setup and agents

#### omabox setup

Links the agent skill and the bar widget, offers the guard; `--remove` undoes all of it, `--aquamarine` builds aquamarine's fix.

Examples:

```
$ omabox setup
$ omabox setup --remove
```

```
omabox setup [--remove]                                your links (skill, bar widget), settings dir, agent guard
omabox setup --feedback-skill|--no-feedback-skill      opt in to the omabox-feedback skill, or out again
omabox setup --aquamarine [--force]                    build omabox's aquamarine: the fix, and its own patches
```

`omabox help setup` adds:

aquamarine's fix for nested Wayland outputs (hyprwm/aquamarine#415, until the system's has it: a release, or a package patched with it; omabox looks for what the fix added, not the version): a headless box on an NVIDIA render node and confirm-close need it, and `up` refuses them without it; `omabox setup --aquamarine` builds it (a checkout's build/prefix, else ~/.local/share/omabox), with omabox's own fixes for interactive boxes on top: a key held when the window loses focus is released, and in a monitor's window your pointer lands on that monitor and your cursor stays shown. No system aquamarine has those, so it builds even when the system's has the fix; it builds nothing only when boxes already use this omabox's build (--force rebuilds it). It builds the aquamarine the installed Hyprland links: 0.15.1 with the fix for Hyprland 0.56 (libaquamarine.so.14), 0.16.0 for Hyprland 0.57 (.so.15; there Hyprland itself puts the pointer on the right monitor). For a Hyprland that links another, it builds nothing, says so and exits 0: boxes use the system's. `omabox --version` says which one new boxes use: a private build, or the system's (with the fix, patched with it, or without it). A git worktree of omabox with no build of its own uses its main checkout's build/prefix, and says so. OMABOX_AQUAMARINE=system: the system's aquamarine all the same (testing).

`omabox setup --feedback-skill` links the omabox-feedback skill next to the omabox one, for people who want to report what omabox got wrong from their own agent sessions: it runs only when you ask (/omabox-feedback), shows the drafts it would file and asks before posting anything. Off unless you opt in; a later `omabox setup` keeps it, `--no-feedback-skill` (or `--remove`) takes it out.

#### omabox guard

Opt in, and agents' shells get a display that doesn't exist: a window they forget to box fails instead of reaching yours.

Examples:

```
$ omabox guard on
$ omabox guard exec -- opencode
```

```
omabox guard [on|off [claude|codex]]                   the agent guard: show, add, remove
omabox guard exec -- AGENT [ARG...]                    run any other agent under the guard
```

`omabox help guard` adds:

The agent guard (opt-in) gives agents' shell commands (Claude Code, Codex) a display that does not exist, so a window, hyprctl or grim outside a box fails instead of reaching your desktop; omabox still works, and `omabox host` runs a command you asked for on the real desktop.

#### omabox broker

Lets agents inside ai-jail drive boxes of their own, kept to what the jail has.

Examples:

```
$ omabox broker on
```

```
omabox broker [on|off]                                 let agents inside ai-jail drive their own boxes
```

`omabox help broker` adds:

An agent inside ai-jail cannot enter a box: `omabox broker on` (a systemd user socket) lets its omabox hand commands to omabox outside, which keeps the jail's boxes to what the jail has (its project, its network or none) and to themselves. It prints the lines to add to ~/.ai-jail.

#### omabox brief

The lines a subagent needs to drive a box, instead of the whole skill.

Examples:

```
$ omabox brief -b app-menu
```

```
omabox brief [-b NAME]                                 ~15 lines for a subagent's prompt: the box, its windows, the rules
```

`omabox help brief` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`omabox brief -b NAME` is for an agent that hands box work to a subagent: paste its output into the subagent's prompt and the subagent needs no skill. It names the box, its size and its windows (each with a --window SEL that finds it alone, six at most), then the rules: -b NAME on every call, one literal command per call, look, act once, look again, never resend unseen input, no sleep, never the real desktop, the box HOME's host path for the file tools, scripts there for several shell steps, stay in your worktree; and to load the skill when that is not enough. With no box up, the same for a box the subagent starts itself (up --new), and a note on stderr. Exit 0 but for a usage error.

#### omabox help

One command's options, its notes with `--long`, or what each exit code means.

Examples:

```
$ omabox help record --long
$ omabox help exit-codes
```

```
omabox help [COMMAND [--long] | --all | exit-codes]   one command's options (--long: its notes); --all: these lines; exit codes
```

`omabox help help` adds:

Exit codes, the same in every command:   0         done, or the condition held (wait, events --until; check run: nothing changed)   1         it ran and failed, or the answer is no: no such box up, a refusal, wait's "unknown" (the             box went down), tree finding nothing, which's "not in a box"; check: a checkpoint changed;             check wants: none of its IDs taken this run   2         called wrong: an unknown option or command (the nearest one named), a value missing or             not of its form, a word too many or too few; said with omabox help COMMAND. Also: --window             SEL matching no window or several (listed), which PID for a process gone, check's errors   3, 4      check run: the scenario itself failed / no baseline to compare with   124       not in time: wait, --wait (keys, click, scroll, drag, run -d), events --until   125       run: omabox's own failure (no box, a bad option, a throwaway that did not start, the box             going down while the command ran), never the command's   126, 127  run: the command could not be run / was not found in the box   N         run, hyprctl: the command's own status, passed through; run -d: the job's, when it ended             at once (--wait: before the screen settled)   128+N     ended by signal N (130: Ctrl-C) An option that takes a value takes it as --opt VALUE or --opt=VALUE, in every command. A form on its way out still works for one minor release, warned on stderr ("omabox: deprecated: OLD: write NEW"), then is refused (2). OMABOX_STRICT=1 refuses it at once (2), for CI.

#### omabox --version

The version, and which aquamarine new boxes use.

Examples:

```
$ omabox --version
```

```
omabox --version [--json]                              and which aquamarine new boxes use
```

`omabox help --version` adds:

aquamarine's fix for nested Wayland outputs (hyprwm/aquamarine#415, until the system's has it: a release, or a package patched with it; omabox looks for what the fix added, not the version): a headless box on an NVIDIA render node and confirm-close need it, and `up` refuses them without it; `omabox setup --aquamarine` builds it (a checkout's build/prefix, else ~/.local/share/omabox), with omabox's own fixes for interactive boxes on top: a key held when the window loses focus is released, and in a monitor's window your pointer lands on that monitor and your cursor stays shown. No system aquamarine has those, so it builds even when the system's has the fix; it builds nothing only when boxes already use this omabox's build (--force rebuilds it). It builds the aquamarine the installed Hyprland links: 0.15.1 with the fix for Hyprland 0.56 (libaquamarine.so.14), 0.16.0 for Hyprland 0.57 (.so.15; there Hyprland itself puts the pointer on the right monitor). For a Hyprland that links another, it builds nothing, says so and exits 0: boxes use the system's. `omabox --version` says which one new boxes use: a private build, or the system's (with the fix, patched with it, or without it). A git worktree of omabox with no build of its own uses its main checkout's build/prefix, and says so. OMABOX_AQUAMARINE=system: the system's aquamarine all the same (testing).

### Other

#### omabox window

```
omabox window [-b NAME] [--window SEL] (--size WxH | --float | --tile | --fullscreen [off] | --maximize [off]) [--json]   one window floated at that size, tiled, fullscreen or maximized
```

`omabox help window` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`window` changes one window of the box (--window SEL; none: the active one) in the box's own Hyprland, where `mode` sizes the whole screen: a narrow layout, a sheet that wraps. --size WxH floats it (a tiled window takes no size of its own), makes it that size in layout pixels, as `windows` gives sizes, and centres it on its monitor's free area; again to try another width. --float floats it where Hyprland puts it (the size it last floated at); --tile tiles it again. It prints the window as it is then, `0x... CLASS "TITLE" floating at X,Y WxH` (--json: the object `windows --json` lists). A size the window did not take is exit 1, saying the size it took: an app's smallest or largest size bounds it (9x20 for a terminal asked 5x5). A fullscreen or maximized window is refused (exit 1, nothing changed). --fullscreen makes it fullscreen (the whole screen, no bar: for a take or a shot of the app alone), --maximize maximizes it (the work area, the bar kept); each sets the state, never toggles it: again changes nothing, and --fullscreen off (--maximize off) takes it out of that state only (a maximized window stays so after --fullscreen off). The line says the state after the place: `tiled, fullscreen at 0,0 1920x1080`; `windows --json` has it as fullscreenMode (none, maximized, fullscreen). The app redraws at its new size a moment later: `wait still` before a shot of it.

#### omabox jobs

```
omabox jobs [-b NAME] [--json]                         the box's run -d jobs: pid, age, processes, log, command
```

`omabox help jobs` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`wait job [JOB]`: until the command of `run -d` job JOB (its pid, as `jobs` lists it; none: the latest `run -d`'s) has exited, satisfied with how it ended ("exited with status 0", "was killed by SIGTERM (143)"), at once for one that ended already; --gone: until nothing of its session runs either (what it forked: an app a launcher left). `wait log [JOB] RE [-i]`: until a line of the job's log (as `log run [JOB]` has it, every line from its first: one there already counts) matches RE (grep -E; -i: either case), satisfied with that line; a job that ended with no such line is unknown (exit 1), as nothing more will come. Each tried every 100 ms. Never a host `pgrep` or a loop over the log file. `wait log LOG RE [-i]` (LOG a box log, as `log` names them: shell, hyprland, apps, journal, ...; RE also as --grep RE): until LOG gets a line RE matches written after the wait began, printed with it (a plugin's line in the shell log). A box log has lines from before: they do not count, and a 124 says one that was there (`--since 0` counts the whole log). --since OFFSET reads from that byte; --json's offset is where the line found ends, for the next wait's --since. A log begun anew meanwhile (restart-shell starts the shell's) is read from its start, said. Hyprland's new lines come from `hyprctl rollinglog` (its file is written 8 KiB late), every 250 ms: no --since there. `wait notification RE [-i]` (#430): until a notification reaches the box's server (as `log notifications` has it) whose summary or body RE matches (grep -E, each with its newlines as spaces; not its app name), printed with it; --json adds the record (`notification`: its id, hints, actions). One sent before the wait does not count, and a 124 says one that was there (`--since 0` counts the whole log; --json's offset is the next wait's --since). One sent with no server counts too: its line says `(no id) ... -- not shown: WHY`. `wait for DURATION`: that long, then "satisfied: waited ..., a fixed time": for a time that is the point (a timer under test), where a foreground sleep is blocked. Not to let an app settle: wait for what it does (still, change, window, job, log, until).

`jobs` lists the box's `run -d` jobs still running, oldest first: PID (the job's command's, in the box, as `windows` shows its windows'), AGE, PROCS (processes of its session), LOG (its log, from the host) and COMMAND; --json: [{pid, age (seconds), processes, log, argv}]. A job that ended is not listed (its end, when early, is said by the next command). `stop JOB...` stops each job as `run -d --replace` stops one: SIGTERM to its session (what it forked included), SIGKILL after 5 s, then until its windows are gone (3 s), each said with how long it took. JOB is a job's pid, or the pid of any process of its session (a window's PID from `windows`); --all: every job. Its signals go through a pidfd of each process, checked to be the box's, never a pid number on the host. A stopped job's end is not said as a warning. Another process of the box: `omabox run -- kill PID`. Not a `run -d` job's pid: exit 1, nothing stopped.

#### omabox stop

```
omabox stop [-b NAME] (JOB... | --all)                 stop run -d jobs (JOB: a pid jobs lists), their windows gone
```

`omabox help stop` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`jobs` lists the box's `run -d` jobs still running, oldest first: PID (the job's command's, in the box, as `windows` shows its windows'), AGE, PROCS (processes of its session), LOG (its log, from the host) and COMMAND; --json: [{pid, age (seconds), processes, log, argv}]. A job that ended is not listed (its end, when early, is said by the next command). `stop JOB...` stops each job as `run -d --replace` stops one: SIGTERM to its session (what it forked included), SIGKILL after 5 s, then until its windows are gone (3 s), each said with how long it took. JOB is a job's pid, or the pid of any process of its session (a window's PID from `windows`); --all: every job. Its signals go through a pidfd of each process, checked to be the box's, never a pid number on the host. A stopped job's end is not said as a warning. Another process of the box: `omabox run -- kill PID`. Not a `run -d` job's pid: exit 1, nothing stopped.

#### omabox tray

```
omabox tray [-b NAME] [--json] [--all]                 the box's tray items and their menus (rows, checked, enabled)
omabox tray menu ID [-b NAME] [--json] [--all]         one item's menu, opened as a host opens it (AboutToShow)
omabox tray activate ID [-b NAME] [--secondary]        a left (--secondary: middle) click on its icon, over the bus
omabox tray click ID LABEL [-b NAME] [--index N]       the menu row named LABEL clicked, as the bar's card clicks it
```

`omabox help tray` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`tray` reads the box's tray over its own session bus (never yours): each StatusNotifierItem the box's watcher has, `ID "TITLE" [status]` (active, passive, needs attention; Omarchy's bar leaves passive ones out), then its dbusmenu's rows in `tree`'s words, indented by submenu: `menu item "Quit"`, `check menu item "Sync" [checked]`, `radio menu item "Jazz" [unchecked]`, `menu "Stations"` (a submenu), `separator`, with [disabled]; hidden rows are left out (--all keeps them, [hidden]). An item with no dbusmenu says `(no menu)`. A listing sends the apps nothing. --json: an array, an object an item (`id, title, status, category, service, path, menu, item_is_menu, rows`), each row `id, label, role, enabled, visible, toggle, checked, rows`, hidden ones too. ID names an item: its Id, else its title (any case), else its bus name (`:1.42`), else a part of its Id or title; two items matching: exit 2, both listed; none: exit 1, the box's listed. `tray menu ID` sends AboutToShow first, as a host opening the menu does (an app may fill it then), and prints that item; an item with no dbusmenu is asked ContextMenu instead (it shows a menu of its own, a window or popup: omabox windows, tree). `tray activate ID` is Activate (a left click on the icon; refused for an ItemIsMenu item, whose click opens its menu), --secondary SecondaryActivate (a middle click). `tray click ID LABEL` sends the dbusmenu `clicked` event to the row named LABEL (any case; an exact label wins over a part of one), each submenu on its way sent AboutToShow first: its line said on stderr, the row as the app then has it on stdout (`check menu item "Sync" [unchecked]`). Several named so: exit 2, numbered with their submenus, and --index N clicks that one. Exit 1, nothing sent: no row is named LABEL, or the one named so is hidden, disabled (itself or its submenu) or a submenu. None of it draws the bar's menu card: the bar publishes no place for an icon (no accessible items), so a real click on one is `click X Y` at the icon a shot shows. `tray menu`, `activate` and `click` are actions for `shot --burst --after` and `record -- ACTION` (what a row opens, as it opens); a bare `tray` reads only, and is refused there.

#### omabox find

```
omabox find [-b NAME] --image FILE [--similar 0.95] [-g GEOM | --window SEL] [--all] [--json]
                                                       where an image (a crop of a shot) is: X,Y WxH SCORE each
```

`omabox help find` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--window SEL (or -w SEL): a window: active (or --active), 0x... (its address), pid:N, class:RE, title:RE, a word

SEL picks one window: active, its address (0x...), pid:N, class:RE, title:RE, initialClass:RE, initialTitle:RE (any case), or a word (its class or the class's last part, nautilus for org.gnome.Nautilus, or part of its title; failing those, a hyphen-separated part of the class, portal for xdg-desktop-portal-gtk); repeat to narrow. None or several is exit 2, with the candidates (`wait window SEL` asks for a window like it: any of several does, each named); -w is --window, and --active is --window active wherever it goes. `shot --window` is the window's own pixels, covered or on another workspace too, cut at its edges: a menu or popup reaching past them is cut off (Hyprland says nowhere where a window's popups are), so take the screen around it with `shot -g "X,Y WxH"` (the window's place is on the shot's stderr line) or a whole shot, and click into that with `click --in`; `click --window` takes the window's coordinates and focuses it first when it is off screen or covered there (--no-raise refuses instead); a layer surface over that point (a notification toast, a panel) is said on stderr, the click sent (it goes to the layer where the layer takes input; only its rectangle is known), and --no-raise refuses (`wait layer NAMESPACE --gone` waits one out); one spanning the screen (Omarchy's notifications and dock, input on their items only) is said as one the input may go to, never refused; `windows` lists them under its table. The dock on a workspace that is not floating (or behind a fullscreen window) takes no input at all: it is not said, nor listed. A click, scroll or drag at the screen's X Y says a layer certainly over the window there the same way (never refused; a spanning one not). `keys --window` focuses it, then types.

`find --image FILE` finds a picture where there is no accessibility tree (the shell, its plugins, the bar, a terminal): FILE is a PNG, best a crop of a shot of the box (`shot -g "X,Y WxH" -o FILE`), whose comment records the scale it was taken at. Each match is a line `X,Y WxH SCORE` in the layout's coordinates, in reading order (`-g`'s, click's, shot -g's), 1 the same pixels; exit 1 none, with the best score seen and where. Several: all listed (20, --all every one) and said on stderr, never one taken for you. --similar (0.95) is the score a match needs: normalised correlation of the colours, less for another contrast or tone (a grey switch is not its blue self); an image of one colour by its difference, transparent pixels not compared. A box drawn at another scale than FILE's resizes it and says so, then needs 0.8 unless --similar says; its one match with another place within 0.05 of it is a near tie (a look-alike scores that close once scaled), said on stderr and as --json's near_tie. -g looks in a region, --window SEL in that window's own pixels (covered or not). `click --image FILE` clicks the middle of the one match (--offset DX,DY beside it: a label's field), several exit 2 numbered for --index N, a near tie exit 2 with both (a crop shot in this box tells them apart); `wait image FILE [--gone]` polls for it, a near tie not counted as there (0, 124, 1 as the other waits). Each takes a frame and searches it in about 50-100 ms. A jailed agent's FILE is read by its own omabox.

#### omabox plugin

```
omabox plugin [-b NAME] (add PATH|ID | remove ID)      a shell plugin into a box that is up (as up --plugin), or out
```

`omabox help plugin` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--plugin PATH|ID: a shell plugin, read-only, enabled where its manifest says; `up` and `restart-shell` warn when Omarchy's validator or the shell refuses it (`ls --json`: plugin_status). One the box has at its own path (in the repo `up` runs from, a same-path --ro-bind or an --overlay) is linked to there, as on a desk, so readlink -f leads into its repo; any other is mounted (plugin_status: via).

`plugin add PATH|ID` puts a plugin in a box that is up as --plugin would have: read-only, linked to where the box has it at its own path or mounted, made known to the shell (a rescan, until it lists it) and enabled, its state said (`ls --json`: plugin_status). `plugin remove ID` takes one out (one from up's --plugin too): disabled, unmounted or unlinked, rescanned. A link made by hand in the box HOME works only for a folder the box has at its own path, and `omarchy plugin enable` right after `rescanPlugins` says "is not known" until the rescan is done; `plugin add` does both. Not inside ai-jail, nor on a box a jail started (up --plugin there).

#### omabox dnd

```
omabox dnd [-b NAME] [on|off] [--clear]                the box's Do Not Disturb; --clear: its toasts dismissed
```

`omabox help dnd` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--dnd, `dnd on`: the box's Do Not Disturb, in its own Omarchy shell (never your desktop's): new notifications stay off its screen, so no toast lands over a window's corner between steps (Omarchy still shows a critical notify-send, a verification code and its own action toasts, such as a layout change's). --dnd also dismisses any toast up when the box is ready; `dnd --clear` does that at any time. Bare `dnd` prints on or off. A box `--from` a save keeps the save's (Omarchy 4.5 keeps it in its notifications state). --no-dock, `dock off`: Omarchy 4.5's dock disabled in the box's shell (its shell.json's disabledPlugins, as `omarchy plugin disable omarchy.dock` writes it), its layer gone. The dock shows only on a floating workspace; elsewhere its layer stays mapped, taking no input. Bare `dock` says, per monitor, whether it is shown (its icons take input), tucked away (auto-hide or a maximised window: only the strip along its edge, until the pointer reaches it) or hidden (none); --json the same as an object. Both refuse a box with no shell; dock one whose Omarchy has none (before 4.5).

#### omabox dock

```
omabox dock [-b NAME] [on|off | --json]                where Omarchy 4.5's dock takes input in the box; off, on
```

`omabox help dock` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--dnd, `dnd on`: the box's Do Not Disturb, in its own Omarchy shell (never your desktop's): new notifications stay off its screen, so no toast lands over a window's corner between steps (Omarchy still shows a critical notify-send, a verification code and its own action toasts, such as a layout change's). --dnd also dismisses any toast up when the box is ready; `dnd --clear` does that at any time. Bare `dnd` prints on or off. A box `--from` a save keeps the save's (Omarchy 4.5 keeps it in its notifications state). --no-dock, `dock off`: Omarchy 4.5's dock disabled in the box's shell (its shell.json's disabledPlugins, as `omarchy plugin disable omarchy.dock` writes it), its layer gone. The dock shows only on a floating workspace; elsewhere its layer stays mapped, taking no input. Bare `dock` says, per monitor, whether it is shown (its icons take input), tucked away (auto-hide or a maximised window: only the strip along its edge, until the pointer reaches it) or hidden (none); --json the same as an object. Both refuse a box with no shell; dock one whose Omarchy has none (before 4.5).

#### omabox polkit

```
omabox polkit [-b NAME] ask [--action ID] [--message TEXT] [--icon NAME] [--prompt TEXT] [--accept PASSWORD]
              [--detail KEY=VALUE]... [--timeout 60s] [--delay DURATION] [--json]
                                                       the box's polkit agent asked for a password: how it ended
omabox polkit [-b NAME] agents [--json]                the polkit agents registered in the box
```

`omabox help polkit` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

--polkit: a polkit agent in the box (the shell's polkit plugin, a copy of it under test, a GTK or Qt agent) registers and is asked, as on a desktop, and the end of each request is the agent's own. A box has no system bus and no logind session, and never gets yours: it gets a system bus of its own where only polkit's name can be owned, by a stand-in authority, which keeps the agents as polkitd does (one per session, dropped when they leave the bus) and makes a request only when `polkit ask` does. In place of PAM it answers polkit's agent helper with a password prompt, and takes the one password `ask --accept` names (a test's, never yours). It decides nothing for any service: pkexec, pkcheck and mechanisms get no answer from it. The bus is the box's (its processes share one uid, so one can answer in the stand-in's place): what `polkit` prints of it is bounded and plain. The box's processes are in a session named "omabox" (XDG_SESSION_ID). Logs: `log polkit`.

`polkit ask` makes one request, as polkitd makes one: BeginAuthentication on the box's agent (the one registered for its session, else the last one), with --action (org.omabox.test), --message (else "Authentication is required for ACTION"), --icon and each --detail, the box user as the identity. Each password the agent sends goes to the box's helper, which takes only --accept's (none: every one is wrong) after --delay (0; a checking state to see), as SUCCESS or FAILURE. It waits for the end: one line, "authenticated: the agent at :1.5 /PATH, 2 passwords (1 wrong)". authenticated: the helper took the password and the agent returned; not-authenticated: the agent returned without; cancelled: the agent cancelled (its user dismissed it); timeout: no end in --timeout (60s), so the authority sent CancelAuthentication, as polkitd does when its caller gives up (exit 124); agent-gone: it left the bus; no-agent. Exit 0 authenticated, 124 timeout, 1 any other end. --json: result, tries, wrong, agent, path, action, why. Start it in the background (`omabox polkit ask ... &`), then drive the dialog: `wait layer`, `keys`. `polkit agents`: subject, bus name, object path (and fallback) of each agent registered.

#### omabox pid

```
omabox pid [-b NAME] [hyprland|shell] [--in-box] [--json]   the host PID of the box's Hyprland (or shell)
```

`omabox help pid` adds:

-b NAME (or --box NAME) picks the box, in every command that takes one; it goes before the command too (omabox -b NAME windows).

`omabox pid`, `which` the other way round: the host PID of the box's Hyprland (the default) or its shell, for /proc/PID/maps, perf or strace on the host; --in-box the PID as the box numbers it (`gdb --pid`, `omabox run -- kill`). --json: {box, process, pid, box_pid}. Nothing on stdout and exit 1 when it is not running.

#### omabox doctor

```
omabox doctor [--json] [--smoke]                       can this machine run boxes? what to install if not (read-only)
```

`omabox help doctor` adds:

`omabox doctor` looks at what a box needs, where a box looks for it (/usr/bin), and changes nothing: Omarchy and your theme (without Omarchy: information, plain boxes only), Hyprland (0.56+, a Lua config), the config your desktop's Hyprland loaded (its status, a read: a .conf one warns, as interactive mode, peek and keys-to-box need Lua), the aquamarine boxes would use (with or without #415), labwc, quickshell (needed on Omarchy only), bwrap (0.11+), pasta, grim (-T), the programs a box runs, omabox's C tools, user namespaces, no_new_privs, /dev/net/tun, the render nodes (driver, software-only) and the one a box uses, socket path length, and which omabox your shell's PATH and your desktop session's find (agents started from the desktop get the latter). A check that fails or warns has a fix line: the install command for your distribution's family (/etc/os-release's ID, else ID_LIKE: Arch, Debian and Ubuntu, Fedora, openSUSE, NixOS; Arch's package names for any other). It installs, builds and asks for nothing. Exit 1 when a check fails, 0 otherwise (warnings too). --json: {ok, os {id, id_like, family}, checks [{id, status ok|info|warn|fail, found, fix [...]}], smoke}. --smoke, when every check passes, also starts a headless box (doctor-PID), takes a shot (kept: its path is said) and takes the box down.
