---
name: panama-sudo
description: Use whenever a command needs root on a Panama machine — any sudo, pkexec, or privileged system change. Panama routes privilege through a wrapper that shows the user your reason beside the password prompt.
---

# panama-sudo

Never run bare `sudo` or `pkexec` on a Panama machine. Use:

```sh
panama-sudo --reason "why this needs root" -- command args…
```

`--reason` must be the first argument; the `--` separator is optional. The reason is displayed on
the desktop's own polkit prompt **beside** — never instead of — polkitd's description of the
action, because anything can claim any reason. That is the trust model, and it shapes how you
write the reason: state what the command does, not an assurance that it is safe.

- Good: `--reason "Install the fwupd package so firmware updates can be checked"`
- Bad: `--reason "Safe maintenance task"`

With no `--reason`, no running shell, or no `qs` on PATH, it degrades to plain `pkexec` — so it
is always the right call, even in a TTY or a broken session.

One reason per privileged action. Do not batch unrelated root commands behind a single vague
reason; the user approves what the prompt says, and the prompt should say everything.

House precedent: `bin/panama-migrate` documents the rule — root work goes through
`panama-sudo --reason "..."`, never bare sudo — and every shipped migration follows it.