# How Omarchy Privileged Commands Handle Sudo vs Pkexec Escalation

> Discover how Omarchy handles privileged commands using sudo vs pkexec for seamless escalation. Learn its smart approach to terminal and non-terminal environments.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Omarchy selects `sudo` when a terminal is available for password entry and `pkexec` when running without a terminal (e.g., UI actions or background tasks) to ensure appropriate privilege escalation without blocking the user interface.**

The `basecamp/omarchy` repository implements a context-aware privilege escalation model that distinguishes between interactive terminal sessions and graphical or background operations. This approach ensures that **privileged commands in Omarchy** obtain root rights through the most appropriate mechanism for the calling context, maintaining both security and usability across different execution environments.

## The Terminal-Based Escalation Model

Omarchy's privilege escalation logic hinges on a single deterministic factor: whether the calling process has a terminal attached (`tty`). According to the source code in [`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md), the system evaluates the execution context and selects the escalation method accordingly:

- **`sudo`** – Used when the caller has a terminal attached, allowing the user to type a password directly into the command line interface.
- **`pkexec`** – Used when the caller lacks a terminal (such as background tasks, UI-triggered actions, or scripts launched from menus), triggering a graphical Polkit authentication dialog instead.

This model prevents UI blocking in graphical environments while preserving the standard terminal workflow for command-line operations.

## Implementation Guidelines from Source Code

The specific rules governing these choices are documented in the Omarchy agent skills specification and referenced from the top-level [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md) (lines 68-70).

### Terminal-Attached Contexts (Sudo)

For commands executed within a terminal session, Omarchy mandates the use of `sudo`. The documentation at line 53 of [`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) states:

> For privileged commands, follow the Privilege Escalation rules below: `sudo` when a terminal is available for the password prompt, `pkexec` when it is not.

This ensures that users receive password prompts in their current terminal window without spawning unnecessary graphical dialogs that might break terminal-based workflows or SSH sessions.

### Non-Terminal Contexts (Pkexec)

When the calling context lacks a terminal—such as desktop menu items or automated background scripts—Omarchy requires `pkexec` to display a graphical authentication dialog. Lines 91-93 of [`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) specify:

> Use `pkexec` **only** when the caller cannot interact with a terminal or cannot run a background process. Do not replace `sudo` with `pkexec` merely because a command is "non‑interactive".

This distinction is critical for background operations that must not hang waiting for terminal input that will never arrive.

### Self-Managing Commands

The guidelines explicitly prohibit wrapping commands that already handle their own privilege elevation. Developers should not add `sudo` or `pkexec` prefixes to tools that internally manage escalation, as this could cause double-authentication prompts or permission conflicts.

## Practical Code Examples

The Omarchy codebase demonstrates this escalation model through several implementation patterns.

**Terminal-based installation using sudo:**

```bash

# Example 1 – a command run from a terminal (uses sudo)

omarchy-cmd-missing some-tool && sudo apt-get install some-tool

```

**Background/UI operation using pkexec:**

```bash

# Example 2 – a UI menu item that needs root but has no terminal (uses pkexec)

# The Omarchy helper automatically picks pkexec when the menu runs in a non‑tty context.

omarchy-update-stay-awake \
    # …internal logic…

    inhibit_runner=(pkexec)   # <-- pkexec chosen because the caller is a background script

```

**Adaptive script that checks for terminal availability:**

```bash

# Example 3 – a script that must work both interactively and non‑interactively

if [[ -t 1 ]]; then      # terminal attached

    exec sudo "$@"
else
    exec pkexec "$@"
fi

```

The `[[ -t 1 ]]` test checks if file descriptor 1 (stdout) is associated with a terminal, providing a runtime determination of which escalation method to invoke.

## Key Source Files and Test Coverage

Several files in the `basecamp/omarchy` repository define and enforce this privilege escalation model:

- **[`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md)** – Contains the complete Privilege Escalation specification (lines 53, 91-93) that agents must follow when generating or executing privileged commands.

- **[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)** – Top-level documentation (lines 68-70) that summarizes the escalation rules and points to the detailed SKILL.md specification.

- **[`test/shell.d/polkit-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/polkit-test.sh)** – Test suite that verifies `pkexec` usage when a terminal is unavailable, ensuring the escalation logic behaves correctly in non-tty contexts.

- **`bin/omarchy-update-stay-awake`** – Production script that selects `pkexec` for background inhibition tasks where no terminal is present.

- **`bin/omarchy-dns`** – Utility script that elevates via `pkexec` when re-executing itself in contexts lacking terminal access.

## Summary

- **Omarchy privileged commands** use `sudo` when a terminal is available and `pkexec` when running without a terminal.
- The decision logic relies on checking terminal attachment (typically via `[[ -t 1 ]]`) to determine the appropriate escalation mechanism.
- `pkexec` is reserved specifically for UI-triggered actions and background tasks where terminal interaction is impossible, not merely for non-interactive commands.
- Commands that manage their own privilege elevation should not be wrapped with either `sudo` or `pkexec`.
- Implementation rules are enforced through agent specifications in [`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) and verified by the [`test/shell.d/polkit-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/polkit-test.sh) test suite.

## Frequently Asked Questions

### When should I use pkexec instead of sudo in Omarchy?

Use `pkexec` only when the caller cannot interact with a terminal or runs as a background process without tty access, such as desktop menu items or automated scripts. According to the Omarchy source code, `sudo` remains the default for all terminal-attached contexts even if the command itself is non-interactive.

### Can I replace sudo with pkexec for non-interactive commands?

No. The Omarchy guidelines explicitly prohibit replacing `sudo` with `pkexec` merely because a command is "non-interactive". The determining factor is terminal availability, not interactivity. If a terminal exists, use `sudo`; reserve `pkexec` for contexts where terminal input is impossible.

### How does Omarchy detect whether a terminal is available?

Omarchy scripts typically use the shell test `[[ -t 1 ]]` to check if file descriptor 1 (standard output) is attached to a terminal. This runtime check allows scripts to branch between `exec sudo "$@"` for terminal contexts and `exec pkexec "$@"` for non-terminal contexts, as demonstrated in the `bin/omarchy-dns` implementation.

### Where are the privilege escalation rules documented?

The primary specification resides in [`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) at lines 53 and 91-93, with a high-level summary referenced in [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md) at lines 68-70. These documents form the authoritative source for how agents and scripts must handle privilege escalation within the Omarchy framework.