Controller CLI (kldctl)

Relevant source files

The following files were used as context for generating this wiki page:

• kldctl/src/main.rs
• kaleidux-daemon/src/main.rs
• README.md
• kldctl/Cargo.toml
• kaleidux-daemon/src/orchestration.rs

The Controller CLI (kldctl) is a command-line utility designed to manage and interact with the Kaleidux wallpaper daemon. It serves as the primary interface for users to control playback, manage playlists, query system status, and modify wallpaper selection frequencies without directly editing configuration files or restarting the background service.

The utility functions as an IPC (Inter-Process Communication) client that transmits requests over a Unix domain socket to the kaleidux-daemon. It supports a wide range of operations, including skipping wallpapers, pausing video playback, and managing blacklists.

Sources: kldctl/src/main.rs:20-40, README.md:85-102

Architecture and IPC Flow

The kldctl utility follows a request-response pattern. It parses user input using the clap crate, serializes the command into a JSON format defined by the kaleidux-common crate, and sends it to the daemon's Unix socket.

Communication Sequence

The following diagram illustrates the interaction between the user, the CLI tool, and the background daemon.

The CLI determines the socket path by checking the XDG_RUNTIME_DIR environment variable, defaulting to /tmp/kaleidux-{USER}.sock if the runtime directory is unavailable.

Sources: kldctl/src/main.rs:240-265, kaleidux-daemon/src/main.rs:495-520

Command Structure and Subcommands

The CLI is organized into several functional areas: playback control, metadata management, and system queries.

Playback and Navigation

These commands affect the active wallpaper rendering on specific or all outputs.

Command	Alias	Description	Parameters
next	n	Skips to the next wallpaper in the queue.	--output (optional)
prev	p	Returns to the previous wallpaper in history.	--output (optional)
pause	-	Pauses video wallpaper playback.	-
resume	-	Resumes paused video playback.	-
stop	-	Stops the current wallpaper rendering.	-
clear	-	Shows a black screen on target outputs.	--output (optional)

Sources: kldctl/src/main.rs:70-110, README.md:85-95

Content Management (Love/Blacklist/Playlist)

Users can influence the "Smart Queue" algorithm by "loving" files, which increases their selection frequency, or by managing blacklists and playlists.

• Love/Unlove: The love command accepts a --multiplier (default 2.0). A multiplier of 2.0 makes a wallpaper twice as likely to appear during random selection.
• Blacklist: Prevents specific files from being selected by the daemon.
• Playlist: Allows creating, deleting, and loading specific sets of wallpapers.

System Status and Configuration

The utility provides diagnostic tools to inspect the daemon's state and validate local configuration files.

Output Querying

The query command (alias q) retrieves a list of connected monitors, their resolutions, and the current wallpaper path being rendered on each. The CLI formats this data into a human-readable table.

// Example of Response formatting in kldctl
Response::OutputInfo(outputs) => {
    println!("{:<10} | {:<10} | {:<30}", "Output", "Size", "Current Wallpaper");
    for out in outputs {
        println!("{:<10} | {}x{} | {:<30}", out.name, out.width, out.height, out.current_wallpaper.unwrap_or("none".to_string()));
    }
}

Sources: kldctl/src/main.rs:278-295

Local Configuration Validation

The check-config (alias cc) command is unique because it executes locally within the CLI without connecting to the daemon. It attempts to parse ~/.config/kaleidux/config.toml to ensure the TOML syntax and structure match the requirements defined in the orchestration module.

Sources: kldctl/src/main.rs:188-212, kaleidux-daemon/src/orchestration.rs:135-150

Summary

The kldctl utility is the essential bridge between the user and the high-performance kaleidux-daemon. By leveraging a robust IPC mechanism over Unix sockets and providing a comprehensive suite of subcommands, it enables dynamic control over multi-monitor wallpaper behaviors, transition effects, and playlist management. Its ability to perform local configuration checks and weighted frequency adjustments (via "loving" files) makes it a sophisticated tool for maintaining a personalized and aesthetic desktop environment.

Sources: kldctl/src/main.rs:25-50, README.md:10-20