---
title: Desktop Command Wrappers
description: Small helper scripts for terminal launches, notifications, loading overlays, and workspace placement.
sidebar:
  order: 14
---

These wrappers make other scripts and Hypr bindings friendlier on the desktop. They are intentionally small, but they are useful when composing menu actions or one-shot helpers.

## Run a command in a terminal

`run-in-terminal` opens a command in a new terminal window:

```bash
run-in-terminal 'dot doctor'
```

Modes:

| Mode | Behaviour |
| --- | --- |
| `--shell` | Default. Run the command, then stay in an interactive shell. |
| `--wait` | Run the command, then print a prompt saying Ctrl-D closes or the shell can continue. |
| `--exit` | Run the command and close the terminal when it exits. |

Examples:

```bash
run-in-terminal --wait 'workspace-restore --dry-run'
run-in-terminal --exit 'dot doctor'
```

For `--shell` and `--wait`, the wrapper creates a temporary `ZDOTDIR` so the command runs after shell initialisation, then removes that temp directory from the generated shell startup file.

## Notify around a command

`run-with-notify` runs a command and sends a desktop notification with the result:

```bash
run-with-notify 'Capture' workspace-capture
run-with-notify -a 'Workspace' 'Restore' workspace-restore
```

On success, the notification body is command output or `Done`. On failure, it sends a critical notification with the captured stderr/stdout or `Unknown error`. Both use Omarchy's glyph and spacing format.

## Loading overlay

`popup-loading` shows a singleton GTK layer-shell loading overlay on the focused Hyprland monitor:

```bash
popup-loading show 'Updating...'
popup-loading hide
```

Calling it with only a message also shows the overlay:

```bash
popup-loading 'Loading dashboard...'
```

The overlay keeps a runtime socket and lock under `${XDG_RUNTIME_DIR:-/tmp}`:

```text
popup-loading.sock
popup-loading.lock
```

It reads theme colours from:

```text
~/.config/omarchy/current/theme/colors.toml
```

If theme colours are unavailable, it falls back to a dark default.

## Wrap a command with the loading overlay

`with-popup-loading` shows the overlay, runs the command, then hides the overlay on exit:

```bash
with-popup-loading 'Updating dotfiles...' dot update
```

If no command is passed, it only shows the overlay and lets the shell trap hide it when the wrapper exits.

## Launch on a workspace

`launch-on-workspace` starts a command, waits for a new Hyprland client matching a class regex, then moves that new window to the target workspace:

```bash
launch-on-workspace 3 '^(work-browser|google-chrome)$' 'uwsm app -- google-chrome-stable --new-window'
```

It compares matching client addresses before and after launch. Only a newly detected address is moved.

This helper is used by the work browser launchers documented in [Work Browser Launchers](/knowledge-base/work-browser-launchers/).

## Toggle HDR on the primary monitor

`toggle-primary-monitor-hdr` temporarily enables 10-bit HDR with the full BT.2020 colour gamut and raises SDR content brightness through Hyprland's `sdrbrightness` setting (currently `2.0`):

```bash
toggle-primary-monitor-hdr
```

On the `desktop` host it targets the main `HDMI-A-2` display, preserving the original right-monitor behaviour. On other hosts it targets the focused display, using its live resolution, refresh rate, position, scale, and transform.

Run it again while HDR is active to restore 8-bit SDR colour and normal SDR brightness. Both rules are applied at runtime and are not written to `monitors.conf`.

## Troubleshooting

If `run-in-terminal --exit` closes too quickly, use `--wait` while debugging.

If `popup-loading` fails to show, check that the session supports GTK4 layer shell and that `hyprctl -j monitors` works.

If `launch-on-workspace` launches the app but does not move it, the class regex probably does not match the final Hyprland class. Inspect clients with:

```bash
hyprctl -j clients
```