Every way to talk to LunaDash.

The dev branch exposes one owner-only Unix control socket, a versioned Settings API, the Quickshell shell object and Plugin SDK 2's synchronous C ABI. This page documents the contracts implemented by the current source tree.

Wire protocol and ludashctl

Processes launched by LunaDash inherit LUNADASH_CONTROL. The client still accepts the historical LUDASH_CONTROL, then searches the runtime directory for one unambiguous *-control socket. Prefer LUNADASH_CONTROL in new code.

lunadashctl status
lunadashctl workspace 1
lunadashctl appearance '{"gap":16,"animations":true}'
lunadashctl quit confirm

The CLI sends one compact UTF-8 JSON object followed by a newline. method and value are strings, so structured payloads are JSON encoded inside value. The compositor accepts at most 65,536 request bytes, applies a three-second server timeout and returns one compact JSON object plus a newline.

{"method":"appearance","value":"{\"gap\":16}"}

Invalid JSON returns {"error":"Invalid request"}. An unsupported method/value returns {"error":"Invalid command or value"}. lunadashctl waits up to 1.5 seconds per socket read and refuses responses larger than 1 MiB.

import json, os, socket

path = os.environ.get("LUNADASH_CONTROL") or os.environ.get("LUDASH_CONTROL")
if not path:
    raise RuntimeError("LUNADASH_CONTROL is not set")

request = {"method": "appearance", "value": json.dumps({"gap": 16})}
with socket.socket(socket.AF_UNIX) as client:
    client.settimeout(3)
    client.connect(path)
    client.sendall(json.dumps(request).encode() + b"\n")
    data = b""
    while b"\n" not in data:
        chunk = client.recv(65536)
        if not chunk or len(data) + len(chunk) > 1024 * 1024:
            raise RuntimeError("Invalid LunaDash response")
        data += chunk

response = json.loads(data.split(b"\n", 1)[0])
if "error" in response:
    raise RuntimeError(response["error"])
print(json.dumps(response, indent=2))

Status is the discovery API

Use status to discover client ids, display modes, connection names, plugin ids, available power/session actions and layout actions instead of hard-coding host-specific values.

Each ordinary status.clients[] entry includes a positive session-local id, title, app id, icon, desktop id, X11 flag, workspace, geometry, focus/minimize/maximize/fullscreen/mapped flags and buffer/content sizes. Do not persist these ids across compositor restarts.

Every control method

The tables are aligned with WaylandCompositor::control() on the dev branch. Examples use the CLI form; direct socket clients send the same method/value pair.

Network action payloads

network accepts structured operations, never arbitrary nmcli text. Actions are bluetooth-scan, network-reset, connection-reconnect, wifi-scan, wifi-connect, connection-up/down/delete, device-connect/disconnect, networking-enable, wifi-enable, connection-autoconnect, connection-ipv4-auto/manual, connection-ipv6-auto/disabled and connection-route-metric.

lunadashctl network '{"action":"wifi-scan"}'
lunadashctl network '{"action":"wifi-connect","ssid":"Lab WiFi","password":"..."}'
lunadashctl network '{"action":"networking-enable","enabled":true}'
lunadashctl network '{"action":"connection-ipv4-manual","name":"Lab","address":"192.0.2.20/24","gateway":"192.0.2.1","dns":"1.1.1.1"}'

Shortcut ids

Known actions are focusLeft/Right/Up/Down, groupLeft/Right, reorderLeft/Right, expelWindow, centerColumn, widenColumn, narrowColumn, maximizeWindow, closeWindow, minimizeWindow, launchTerminal, launchFiles, launchLauncher, screenshot, plus workspace1..10 and moveToWorkspace1..10. Values are Disabled or one key with modifiers; at least Meta or Alt is required.

Settings API version 1

settings-describe returns descriptors with id, name, type, category, normalized schema, current values and a SHA-256 revision. The revision hashes schema plus values for optimistic concurrency.

builtin:<extension-target>
plugin:<package-id>:<extension-target>
module:<module-id>:<section>
layout:<active-window-template>

# Read descriptors
lunadashctl settings-describe

# Send the selected target's exact revision with a partial change
lunadashctl settings-update '{"target":"plugin:org.example.motion:window-animation","revision":"<64-hex-sha256>","changes":{"duration":280}}'

If another editor changed the target, the patch fails with Settings changed. Reload before applying this edit.. Schemas can describe boolean, string, integer, number and bounded enum-array fields. Plugin schemas intentionally allow only toggle, select, number and slider controls.

QML shell API

SDK 2 Quickshell plugins receive shell, validated settings and target-specific context before construction. Treat shell.state as read-only and perform mutations through control methods.

import QtQuick

Item {
    required property var shell
    required property var settings
    required property var context

    Text { text: shell.tr("Focused") + ": " + shell.focusedTitle }
    TapHandler { onTapped: shell.command("workspace", "1") }

    Connections {
        target: shell
        function onCommandCompleted(method, result) {
            if (method === "workspace" && result.error)
                context.reportError(result.error)
        }
    }
}

Every visual context adds target, built-in source, builtinSettings, effective mode and reportError(message). A plugin may expose pluginReady: false; a replacement does not hide the built-in until the loader is ready and pluginReady is true.

Native Plugin SDK 2 ABI

Native effects do not receive Qt or wlroots pointers. Hooks run synchronously on the compositor thread over UTF-8 JSON; do not block, retain host pointers, run nested event loops or create lifetime-escaping callbacks/background work.

#include <stddef.h>
#include <stdint.h>

#define LUDASH_PLUGIN_API_VERSION 2u

typedef struct ludash_plugin_api {
    uint32_t struct_size;
    uint32_t api_version;
    const char *metadata_json;
    int (*process)(const char *request, char *response, size_t capacity);
} ludash_plugin_api;

int ludash_plugin_process(const char *request, char *response, size_t capacity);
const ludash_plugin_api *ludash_plugin_entry_v2(void);
int ludash_plugin_write_json(const char *json, char *response, size_t capacity);

The SDK generates ludash_plugin_entry_v2, embeds the built manifest and produces the receipt. The loader checks struct size, API version 2, process pointer and equality between embedded and installed metadata.

{
  "target":"window-animation",
  "mode":"replace",
  "context":{},
  "builtin":{"duration":220,"enterOffset":12,"focusOpacity":0.82,"exitScale":0.9,"easing":"outCubic"},
  "current":{},
  "settings":{"duration":280}
}

builtin is always available. Replacement hooks get empty current; augment hooks receive the previous valid result. Return a complete JSON object and its byte length excluding NUL, or a negative value. The response buffer is 262,145 bytes. Invalid/oversized output quarantines the instance and preserves the built-in/previous result.

The native targets are window-animation, shell-animation, window-rules and window-layout. Their contracts plus every visual target are in the Plugin SDK and registration guide.