cthulhu/REMOTE-CONTROLLER-COMMANDS.md

Cthulhu Remote Controller - Available Commands

This document lists the currently available D-Bus commands in Cthulhu's Remote Controller interface.

Note

: This is a work-in-progress. As more modules are exposed via D-Bus, this document will be expanded. Eventually this will be auto-generated using tools/generate_dbus_documentation.py.

Service-Level Commands

Available on the main service object /org/stormux/Cthulhu/Service:

Service Commands

Command	Description	Parameters	Returns
GetVersion	Returns Cthulhu's version string	None	String (version + revision)
PresentMessage	Present a message via speech/braille	message (string)	Boolean (success)
ShowPreferences	Opens Cthulhu's preferences GUI	None	Boolean (success)
Quit	Exits Cthulhu	None	Boolean (accepted)
ListCommands	Lists available service commands	None	List of (name, description) tuples
ListModules	Lists registered D-Bus modules	None	List of module names

Example Usage

# Get Cthulhu version
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service GetVersion

# Present a custom message
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service PresentMessage s "Hello from D-Bus"

# List available commands
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service ListCommands

# List registered modules
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service ListModules

# Open preferences
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service ShowPreferences

# Quit Cthulhu
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
    org.stormux.Cthulhu.Service Quit

Module-Level Commands

Module-level commands are available and can be discovered via ListModules. Two key additions are:

PluginSystemManager

Session-only plugin control (does not persist preferences):

• ListPlugins
• ListActivePlugins
• IsPluginActive (parameterized)
• SetPluginActive (parameterized)
• RescanPlugins

Plugin Modules

Plugins that expose D-Bus decorators are automatically registered as modules using the naming convention Plugin_<ModuleName> (e.g., Plugin_GameMode, Plugin_WindowTitleReader).

WindowTitleReader (Plugin_WindowTitleReader)

• SetEnabled (parameterized) -> enabled (bool)
• Enabled (runtime getter)

Example:

gdbus call --session --dest org.stormux.Cthulhu.Service \
    --object-path /org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
    --method org.stormux.Cthulhu.Module.ExecuteParameterizedCommand \
    'SetEnabled' '{"enabled": <true>}' false

Busctl example:

busctl --user call org.stormux.Cthulhu.Service \
    /org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
    org.stormux.Cthulhu.Module ExecuteParameterizedCommand \
    s a{sv} b 'SetEnabled' 1 enabled b true false

Check current state

busctl --user call org.stormux.Cthulhu.Service
/org/stormux/Cthulhu/Service/Plugin_WindowTitleReader
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s 'Enabled'

See README-REMOTE-CONTROLLER.md for comprehensive D-Bus API documentation and usage examples.

Verifying D-Bus Service Status

# Check if Cthulhu's D-Bus service is running
busctl --user list | grep Cthulhu

# Introspect the service to see all available methods
busctl --user introspect org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service

# Get detailed service information
busctl --user status org.stormux.Cthulhu.Service

Contributing

To add new D-Bus-accessible functionality:

1. Add @dbus_service.command, @dbus_service.getter, or @dbus_service.setter decorators to methods
2. Register the module with the D-Bus service in src/cthulhu/cthulhu.py
3. Rebuild and test with busctl
4. Update this documentation (or regenerate using tools/generate_dbus_documentation.py when available)

Desktop Environment Compatibility

Cthulhu's D-Bus Remote Controller is desktop-agnostic and works across all Linux desktop environments:

• GNOME, KDE Plasma, XFCE, LXDE
• Tiling window managers (i3, Sway, bspwm, etc.)
• Any environment with D-Bus session bus support

The service uses only standard D-Bus infrastructure with no desktop-specific dependencies.