quickshell-process-action

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

1. Represent commands as argv arrays, e.g. ["playerctl", "play-pause"].
2. Do not use shell strings. Avoid ["sh", "-c", ...] unless a later security contract explicitly approves it.
3. Keep process execution disabled by default in examples (armed: false) and require the caller/spec to opt in.
4. Prefer a signal from the visual button into a dedicated process adapter rather than hiding process code inside decorative UI.
5. Use startDetached() only for intentional one-shot commands that should survive Quickshell reload/quit.
6. 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.