| name | quickshell-process-action |
| description | Use when binding a QML control to a command or process in Quickshell. |
| source_examples | ["examples/quickshell/components/ProcessAction.qml"] |
| source_docs | ["https://quickshell.org/docs/v0.3.0/types/Quickshell.Io/Process/"] |
Quickshell Process Action
When to use
Use this only when a widget needs to invoke an external command, such as playerctl, opening an app, or triggering a safe local helper script.
Steps
- Represent commands as argv arrays, e.g.
["playerctl", "play-pause"].
- Do not use shell strings. Avoid
["sh", "-c", ...] unless a later security contract explicitly approves it.
- Keep process execution disabled by default in examples (
armed: false) and require the caller/spec to opt in.
- Prefer a signal from the visual button into a dedicated process adapter rather than hiding process code inside decorative UI.
- Use
startDetached() only for intentional one-shot commands that should survive Quickshell reload/quit.
- Never include destructive session commands in sandbox examples.
Safety baseline
- Keep work in the project sandbox unless explicitly asked to edit source.
- Do not write to
~/.config/quickshell.
- Do not launch a live persistent widget from a skill; generate/static-review first.
- Keep KDE/Wayland examples free of
hyprctl and FloatingWindow.
Verification
- Command is a list of strings, not one shell string.
- Example remains unarmed or decorative unless the task explicitly calls for a functional command.
- Destructive commands (
poweroff, reboot, logout, hibernate, suspend) are absent from examples unless under a future hardened contract.