cthulhu/REMOTE-CONTROLLER-COMMANDS.md

Cthulhu Remote Controller - Available Commands

This documentation covers the Cthulhu fork maintained by Storm Dragon. Cthulhu is forked from Orca; former Orca maintainers and contributors are part of the project's upstream history, but they are not current maintainers of this fork.

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/Cthulhu1/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)

Example Usage

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

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

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

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

Module-Level Commands

Module-level commands and properties are discovered with standard DBus introspection:

gdbus introspect --session --dest org.stormux.Cthulhu1.Service \
    --object-path /org/stormux/Cthulhu1/Service --recurse

Two key additions are:

PluginSystemManager

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

• ListPlugins
• ListActivePlugins
• IsPluginActive
• SetPluginActive
• 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 -> enabled (bool), notify_user (bool)
• Enabled (property)

Example:

gdbus call --session --dest org.stormux.Cthulhu1.Service \
    --object-path /org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
    --method org.stormux.Cthulhu1.Plugin_WindowTitleReader.SetEnabled true false

Busctl example:

busctl --user call org.stormux.Cthulhu1.Service \
    /org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
    org.stormux.Cthulhu1.Plugin_WindowTitleReader SetEnabled bb true false

Check current state

busctl --user call org.stormux.Cthulhu1.Service
/org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader
org.freedesktop.DBus.Properties Get ss
org.stormux.Cthulhu1.Plugin_WindowTitleReader 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 available module nodes
busctl --user introspect org.stormux.Cthulhu1.Service /org/stormux/Cthulhu1/Service

# Introspect a module to see its methods and properties
busctl --user introspect org.stormux.Cthulhu1.Service \
    /org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader

# Get detailed service information
busctl --user status org.stormux.Cthulhu1.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.