Settings and Configuration Helper

Pearl supplies the settings UI for current Aqueous desktops. Aqueous owns aqueous-config, the configuration backend used by Pearl and other clients. You can also edit the TOML files directly.

Choose a settings frontend

Use Welcome to select Pearl for a packaged desktop. Stable installations use pearl; the Git desktop uses pearl-git and its matching Aqueous helper. Pearl is distributed separately from the compositor. A core-only installation includes the helper without a settings window or shell.

The former aqueous-settings application and Aqueous Settings plugin workflow have been retired. Remove custom launch bindings that target the old executable. Package upgrades remove package-owned GUI files while retaining personal configuration, preferences, drafts, caches, and backups. The optional DMS appearance bridge is a backend integration, not a replacement settings UI.

Configuration areas

The compositor’s configuration remains available regardless of shell choice:

Area	Guide
Layouts, gaps, borders, stacking, and snap zones	Layouts
Window placement, scrolling widths, tags, and popup rules	Window rules
Keyboard, focus, mouse, touchpad, and gestures	Input
Tablet mapping and discovery	Tablets
Keybindings and application commands	Keybindings
Blur, opacity, scaling, and color conversion	Visual effects
Bell feedback and sounds	System bell

Available controls depend on the installed frontend and negotiated helper capabilities. Use the relevant TOML guide for options a frontend does not expose.

Appearance

appearance.toml stores helper-managed font and cursor preferences; the compositor does not parse it. The helper can synchronize supported preferences with GSettings, GTK, Qt configuration, and the selected shell adapter. Adapter results distinguish saved configuration from successful toolkit synchronization.

--shell none selects neutral operation for Pearl. Legacy --shell dms and --shell noctalia adapters remain available to compatible clients. A missing optional toolkit does not invalidate the saved appearance configuration.

For a live cursor change, use aqueousctl cursor. Persistence and toolkit synchronization go through the configuration helper.

Displays

Display settings cover modes, refresh rates, scale, signed logical positions, rotation, output profiles, HDR, SDR white, Auto HDR, and adaptive-sync policy. See Outputs and HDR for TOML setup and runtime checks.

Compatible frontends use the native display preview contract to try a change before saving it. Confirm a working preview with Keep, or revert it. The 15-second confirmation interval starts only after the participating enabled outputs have presented the new state. An unconfirmed preview does not save the candidate configuration.

Production physical-display previews support SDR, HDR, VRR, HDR with VRR, and Auto HDR when hardware checks pass. Mirroring and custom modes remain blocked in the protected physical-preview path, even though the compositor has a separate SDR mirroring feature. Nested backends do not support these previews. See Display previews.

Inspect the configuration backend

These commands are read-only:

aqueous-config version --json
aqueous-config snapshot --shell none
aqueous-config raw --shell none --file outputs

In a Git installation, use aqueous-config-git. The helper resolves the instance’s actual configuration sources, including inherited system files. Clients must negotiate capabilities before using newer collection, display, preview, or operation-recovery interfaces.

Validation and saving

The helper validates candidate edits, preserves comments and unrelated TOML, checks for concurrent file changes, and owns persistence and reload requests. Structured editing supports ordered rules, custom bindings, snap layouts, output declarations, and profile members. Removing a local override restores the normal inheritance rules; an explicit false or zero remains a value.

Protected changes bind the reviewed candidate to the source snapshot. Display changes additionally require the applicable compositor preview authorization. Conflicts require a fresh snapshot and review. A saved file, a successful reload, and a toolkit synchronization result are separate outcomes.

For integration clients, apply --result v1 --operation-id ID enables recoverable results. After a lost reply, query operation-status --operation-id ID instead of blindly repeating the mutation or reload. The helper’s state journal lives under $XDG_STATE_HOME/<instance>/config-writer, defaulting to ~/.local/state/<instance>/config-writer.

The source contracts document exact requests and capability names: helper interfaces, protected collections, and display declarations.