Command-line Tools

aqueousctl is a Wayland client installed with Aqueous. It reads compositor protocol state directly; it does not scrape logs or depend on a background IPC daemon.

Windows

aqueousctl windows
aqueousctl windows --json

The table and JSON forms expose each managed window’s stable identifier, backend, native app_id or XWayland class, title, output, workspace, geometry, active layout, committed content type, state flags, and matched-rule metadata. JSON also includes the xdg-decoration capability, requested mode, effective mode, and whether a configure response is pending. State includes focused, fullscreen, maximized, minimized, floating, always-above/below, fixed-position, and switcher/taskbar suppression where applicable.

Use JSON when feeding a bar, script, diagnostic report, or test:

aqueousctl windows --json | jq '.[] | {title, output, workspace, layout, states}'

To diagnose a client-side title bar while force_ssd = true:

aqueousctl windows --json |
  jq '.[] | {app_id, title, decoration}'

The decoration object contains:

Field	Meaning
capability	xdg-decoration when the client created the protocol object; otherwise unavailable.
requested	The client’s latest none, client-side, or server-side preference.
effective	The mode most recently configured by Aqueous.
configure_pending	Whether the latest request is still waiting for a configure response.

With forced SSD, a cooperating client settles at effective: server-side. capability: unavailable means the compositor cannot negotiate away the application’s decorations.

Generate a window rule

aqueousctl inspect --rule

This emits ready-to-paste [[window]] entries for mapped windows. Native Wayland windows use app_id; XWayland windows use their WM_CLASS as class. The title is included as a commented optional matcher.

Scene graph and layer namespaces

aqueousctl scene
aqueousctl scene --dot > scene.dot

The tree includes node IDs, parentage, node type, enabled state, labels, and geometry. It is useful for finding layer-shell namespaces, popup ownership, blur checkpoints, clipping, and stacking problems. --dot emits Graphviz DOT for visualization.

Outputs

aqueousctl outputs
aqueousctl outputs --json

This is the full wlr-randr-style snapshot: output identity and description, physical size, enabled state, modes, current/preferred mode, position, transform, scale, adaptive sync, and edid_sha256 where available. Use it before writing an output block or output-targeted rule.

When the embedded output service is available, it also includes mirror_of, mirror_status, and mirror_error. See Screen mirroring.

Tablet discovery and configuration

Run these commands inside the Aqueous session:

aqueousctl input devices --json
aqueousctl input generate-config --device DEVICE_ID --id drawing-pen --output OUTPUT
aqueousctl input generate-config --device DEVICE_ID --id drawing-pen --output OUTPUT --write ~/.config/aqueous/input.toml

Discovery reports input devices and their session IDs, persistent identity fields, outputs, the selected input_file, and each tablet’s mapping status and pending flag. Select an entry with type: "tablet". Replace DEVICE_ID with its id and OUTPUT with the intended display’s name in that response. Session IDs select connected devices; generated rules contain persistent matchers instead of those IDs.

Generation requires --device, --id, and exactly one mapping choice:

Option	Result
--output OUTPUT	Map the pen to the selected available, non-mirrored output.
--mapping desktop	Map the pen to the full output layout.
--disabled	Disable matching tablet-tool delivery.

Without --write, generation prints one TOML rule to stdout. --write PATH atomically updates the rule with that id, preserving unrelated settings, comments, file permissions, and existing symlinks. The parent directory must exist. Ambiguous identities, unavailable outputs, malformed or unsupported existing TOML, and detected concurrent file edits cause an error.

The command reports whether the destination is the selected input sidecar. The normal watcher applies active-sidecar writes; generation does not send a full reload. Check discovery again to confirm application. pending: true means a tool must leave proximity before the remap takes effect. Native generation requires internal-policy mode.

See Tablets for HUION/Wacom examples, matching rules, output reconnect behavior, and status explanations.

Live workspace layout

aqueousctl layout --output DP-1 --json
aqueousctl layout --output DP-1 --set stacking --json

The query returns the named output, its active workspace, and the effective layout. --set installs a runtime override for that output/workspace without editing a configuration file. It accepts the canonical layout IDs and returns a structured status on failure.

Overlay-plane diagnostics

aqueousctl overlay-planes
aqueousctl overlay-planes --json

For each output, diagnostics show whether overlay promotion is enabled, backend capability, current decision phase, candidate window and geometry, buffer format/modifier, rejection reason, backoff, attempts, accepts/rejections, promotions, demotions, and fallback retries. This is the first place to check when an overlay_plane = "prefer" rule remains composed.

Cursor theme and size

aqueousctl cursor --json
aqueousctl cursor set --theme Adwaita --size 24 --json

The query reports the effective compositor cursor theme and base size. set applies an installed Xcursor theme and a size from 1 through 512 to every seat and the XWayland default cursor without restarting. Applications subsequently launched by Aqueous inherit matching XCURSOR_THEME and XCURSOR_SIZE values. Native clients may draw their own cursor surfaces.

This is a live change. Use Settings to persist cursor preferences and update toolkit and service activation environments.

Shell state and runtime actions

aqueousctl shell capabilities --json
aqueousctl shell snapshot --json
aqueousctl shell watch --json

The snapshot contains windows, workspaces, outputs, seats, keyboard groups/devices, and session state. watch streams a snapshot followed by newline-delimited JSON deltas. IDs are scoped to the reported compositor session; use the current snapshot to resolve them. Workspace runtime IDs are not the 1–9 workspace numbers used by configuration bindings.

The following forms use ID, WORKSPACE_ID, and NAME as placeholders:

aqueousctl window activate --id ID --json
aqueousctl window close --id ID --json
aqueousctl window state --id ID --fullscreen true --json
aqueousctl window move --id ID --workspace-id WORKSPACE_ID --json
aqueousctl window move --id ID --output DP-1 --json
aqueousctl workspace activate --id WORKSPACE_ID --json
aqueousctl workspace rename --id WORKSPACE_ID --name "Code" --json
aqueousctl keyboard query --json
aqueousctl keyboard set --index 0 --json
aqueousctl keyboard next --json
aqueousctl overview show --output DP-1 --json
aqueousctl overview toggle --output DP-1 --json
aqueousctl overview hide --json

Activation reveals the workspace and restores a minimized window. Moving a window does not request focus-following or workspace activation. Window state also accepts --minimized or --maximized, exactly one state at a time, with eligibility following the compositor’s floating-window policy.

Keyboard indices are zero-based. set and next accept optional --seat and --group selectors and change live XKB state without rewriting TOML. Window/workspace activation accepts --seat; commands requiring a seat may omit it only when exactly one seat exists. aqueousctl session exit --json requests orderly session termination.

Commands fail while locked or under external/comparison policy. JSON replies include ok, status, and sequence. Close and exit report acceptance, not proof of client termination. Initial state and commands have a five-second deadline; a running watch has no idle timeout. Do not automatically retry a timed-out mutation, which may already have executed. Exit codes are 0 for success, 2 for malformed arguments, and 1 for operation/transport failure.

These commands use the versioned Wayland shell protocol. For persistent socket clients, state sequencing, and capability negotiation, see Shell integration and IPC.

Compatibility clients

wlrctl toplevel list remains usable through the legacy foreign-toplevel management protocol. Output-management clients can use zwlr_output_manager_v1; workspace-aware shells can use ext-workspace-v1. The Aqueous-specific window-information protocol adds the richer state consumed by aqueousctl and the settings application.

Compositor command line

aqueous [options]

Useful options include:

• -h and -version.
• -c <command> to replace the default startup init command.
• -log-level error|warning|info|debug.
• -no-xwayland to disable embedded XWayland at runtime.
• -xwayland-scaling <mode> to select the XWayland projection strategy.
• -drm-overlay-planes or -no-drm-overlay-planes for rule-controlled DRM overlay promotion.

The normal policy is internal. external and compare modes are diagnostics that are available only in a build compiled with -Dexternal-policy=true.