labfy-rgb/docs/quickshell.md

Optional QuickShell integration

The CLI runs without QuickShell. This repository does not install a Control Center, copy personal dotfiles or alter compositor/session configuration.

A local integration was validated with QuickShell 0.3.1 and SwayFX 0.6 on the tested laptop. It adds a compact page to an existing Control Center. Its general Catppuccin Mocha theme is independent of the saturated keyboard colors:

Preset	RGB
Violet (first choice)	#8000FF
Blue	#0040FF
Cyan	#00FFFF
Green	#00FF40
Pink	#FF0080
Red	#FF0000
Orange	#FF6000
Yellow	#FFFF00

Process contract

Use native Quickshell.Io.Process and an argument array. For example, the command for a validated violet preset is:

Process {
    command: ["labfy-rgb", "set", "#8000FF"]
    // Start only in response to an explicit user action.
    running: false
}

A production integration should:

• Validate custom colors with ^#[0-9A-Fa-f]{6}$ and integer intensity 0..100.
• Reserve a single shared busy owner before starting the process, including across multiple screen bars. Refuse concurrent writes.
• Use ["labfy-rgb", "set", color] for a preset click; it uses the CLI default intensity of 100%. The optional fourth argument can combine color/intensity.
• Use ["labfy-rgb", "brightness", String(percent)] for intensity and ["labfy-rgb", "auto"] for an explicit firmware button.
• Update a slider draft without spawning processes on every movement. Apply on a deliberate button or a controlled release/debounce strategy.
• Handle both nonzero exit/crash status and failure to start. Clear busy on all completion paths and show a bounded error message.
• Refresh with ["labfy-rgb", "status", "--json"] after a command completes. Validate schema and fields before displaying results.
• Keep the firmware button usable if a previous status/cache read failed; the CLI performs its own identity checks.

Do not use sudo, pkexec, sh -c, bash -c or shell command concatenation. The normal user must already have access to the controller, as described in README. An absolute installed executable path is also acceptable when the session PATH is unsuitable; it should not be a hard-coded personal checkout path.

State and optional restoration

Label cached values as the last commanded color/intensity/mode. Do not imply that observed_mode: "unknown" or a null color is a measured white keyboard. On the tested firmware, auto visibly returned to white; a different firmware may select another effect.

Keep startup restoration disabled by default and require an explicit opt-in. Store only validated, successfully acknowledged preferences. Firmware preference must take precedence over an old color, and uncertain write failures should invalidate replay eligibility. If implemented, use a bounded one-shot startup check with clear error handling, not permanent polling. Do not replay private or corrupt runtime cache bytes across logins. Suspend/resume restoration is not provided or enabled by this project.

The native cache is temporary command history. Persistent UI preferences are a separate opt-in concern. No root service, extra daemon, autostart entry or QuickShell dependency is installed with Labfy RGB.