Skip to main content

Process Management

██████╗ ██████╗  ██████╗  ██████╗███████╗███████╗███████╗
██╔══██╗██╔══██╗██╔═══██╗██╔════╝██╔════╝██╔════╝██╔════╝
██████╔╝██████╔╝██║   ██║██║     █████╗  ███████╗███████╗
██╔═══╝ ██╔══██╗██║   ██║██║     ██╔══╝  ╚════██║╚════██║
██║     ██║  ██║╚██████╔╝╚██████╗███████╗███████║███████║
╚═╝     ╚═╝  ╚═╝ ╚═════╝  ╚═════╝╚══════╝╚══════╝╚══════╝

The dms command provides process management functionality for running, restarting, and killing DankMaterialShell instances. These commands manage the DMS backend server, which in turn spawns and manages the Quickshell UI process as a child, configuring IPC communication between them.

Overview​

DankMaterialShell consists of a Go backend server that spawns and manages a Quickshell UI frontend as a child process. The process management commands orchestrate both components:

  • Launching the DMS backend server
  • Spawning Quickshell as a child process with DMS configuration
  • Configuring IPC communication between backend and frontend
  • Restarting both processes to apply configuration changes
  • Managing daemon and session modes

Quick Start​

Launch DMS:

dms run

Restart DMS (kills existing instances and relaunches):

dms restart

Kill all running DMS instances:

dms kill

Commands​

dms run​

Launch DankMaterialShell by starting the backend server and Quickshell UI process, then establishing IPC communication between them via Unix socket.

dms run [flags]

Flags:

  • -d, --daemon: Run in daemon mode (detached from terminal)
  • --session: Session managed mode (for use with systemd or other session managers)
  • -h, --help: Show help

Examples:

# Run DMS normally (attached to terminal)
dms run

# Run DMS in daemon mode (detached)
dms run --daemon

# Run DMS as a session-managed process
dms run --session

When to use each mode:

  • Normal mode: For testing, debugging, or manual shell management
  • Daemon mode: For background operation without terminal attachment
  • Session mode: When managing DMS via systemd user units or similar session managers

dms restart​

Kill the DMS backend server (along with its Quickshell child process) and relaunch them. This is useful when you've made configuration changes and want to reload the shell.

dms restart [flags]

Flags:

  • -h, --help: Show help

Examples:

# Restart DMS
dms restart

What it does:

  1. Terminates the DMS backend server (which also kills its Quickshell child process)
  2. Cleans up any orphaned Quickshell processes if needed
  3. Relaunches the backend, which spawns a fresh Quickshell instance
  4. Re-establishes IPC communication

Use cases:

  • After modifying DMS configuration files
  • After updating themes or plugins
  • When the shell becomes unresponsive
  • After applying compositor changes that affect DMS

dms kill​

Kill the DMS backend server (which automatically terminates its Quickshell child process) without restarting.

dms kill [flags]

Flags:

  • -h, --help: Show help

Examples:

# Kill all DMS instances
dms kill

Use cases:

  • Stopping DMS before logging out
  • Cleaning up stuck processes
  • Switching to a different desktop environment
  • Troubleshooting process issues

Running DMS at Login​

DankInstall Users

If you used dankinstall, DMS is already configured as a systemd service and starts automatically. You don't need to configure anything here.

Systemd provides automatic startup, session integration, and logging via journalctl. This is the default for dankinstall setups.

# Enable and start
systemctl --user enable --now dms

# Check status
systemctl --user status dms

# View logs
journalctl --user -u dms -f

The dms restart and dms kill commands work regardless of whether you're using systemd or manual startup.

warning

If using systemd, don't add dms run to your compositor config - you'll end up with two instances.

Manual Launch​

Add to your compositor's autostart configuration:

Hyprland (~/.config/hypr/hyprland.conf):

exec-once = dms run

Sway (~/.config/sway/config):

exec dms run

Niri (~/.config/niri/config.kdl):

spawn-at-startup "dms" "run"

Custom Systemd Unit (Advanced)​

Package installations and dankinstall ship a systemd unit file. If you need a custom unit (e.g., for a source build without make install), create ~/.config/systemd/user/dms.service:

[Unit]
Description=Dank Material Shell (DMS)
PartOf=graphical-session.target
After=graphical-session.target
Requisite=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/dms run --session
Restart=always
RestartSec=2
TimeoutStopSec=10

[Install]
WantedBy=graphical-session.target

Then reload and enable:

systemctl --user daemon-reload
systemctl --user enable --now dms

Process Architecture​

DMS operates as a multi-process system with IPC communication:

  1. DMS Backend Server (Go): Handles IPC requests, plugin management, system monitoring, and CLI operations
  2. Quickshell UI Process: Qt/QML runtime that renders the shell interface (spawned as a child of the backend)
  3. IPC Layer: Unix socket communication between backend and frontend
  4. Plugins: Optional processes that extend functionality

Process hierarchy:

compositor (hyprland/sway/niri/etc)
└── dms backend server
    ├── IPC server (Unix socket)
    ├── Plugin manager
    └── quickshell (child process)
        └── Connects to parent via IPC

When you run dms run, the backend server starts first, creates the IPC socket, then spawns Quickshell as a child process. Quickshell connects back to its parent via the Unix socket for commands like brightness control, keybind displays, and other system operations.

Troubleshooting​

DMS Won't Start​

Check if Quickshell is installed:

which qs

Check for conflicting processes:

ps aux | grep quickshell

Try running without daemon mode to see errors:

dms run

Multiple Instances Running​

Kill all instances and restart:

dms kill
sleep 1
dms run --daemon

Configuration Not Reloading​

Use dms restart instead of manually killing processes:

dms restart

Systemd Service Fails​

Check logs for errors:

journalctl --user -u dms.service -n 50

Verify the service file has correct paths:

systemctl --user cat dms.service

Integration with Compositor​

DMS is designed to work with Wayland compositors. The process management commands ensure DMS runs cleanly within the compositor's session:

  • Hyprland: Use exec-once for autostart
  • Sway: Use exec for autostart
  • Niri: Use spawn-at-startup for autostart
  • MangoWC: Use compositor-specific autostart mechanism

When the compositor exits, the DMS backend should automatically terminate, which will also kill its Quickshell child process. If processes don't clean up properly, run dms kill before logging out.

Command Reference​

dms [command] [flags]

Process Management Commands:

  • run [flags]: Launch Quickshell with DMS configuration
  • restart: Kill and relaunch DMS
  • kill: Kill all running DMS instances

Global Flags:

  • -c, --config <path>: Specify custom DMS config directory
  • -h, --help: Show help

Run Command Flags:

  • -d, --daemon: Run in daemon mode
  • --session: Session managed mode

Other CLI Commands​

The dms command also provides other functionality:

  • IPC: dms ipc - Send commands to running DMS instances (see Keybinds & IPC)
  • Keybinds: dms keybinds - Manage keybind cheatsheets (see Keybinds & Cheatsheets)
  • Brightness: dms brightness - Control device brightness (see Brightness Control)
  • Dank16: dms dank16 - Generate color palettes (see Dank16)
  • Plugins: dms plugins - Manage DMS plugins (see Plugins Overview)
  • Update: dms update - Update DankMaterialShell
  • Version: dms version - Show version information

Run dms --help for a complete list of available commands.