Skip to main content

Process Management

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

The dms command provides process management functionality for running, restarting, and killing DankMaterialShell instances. These commands manage both the DMS backend server and the Quickshell UI process, configuring IPC communication between them.

Overview​

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

  • Launching the DMS backend server
  • Starting Quickshell 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 all existing DMS processes (both backend and Quickshell) 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
  2. Kills all running Quickshell processes with DMS configuration
  3. Relaunches both backend and frontend
  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 all running DMS processes (both backend server and Quickshell UI) 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​

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"

Systemd User Unit​

Create a systemd user service for automatic session management:

File: ~/.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

Enable and start:

# Reload systemd to recognize the new unit
systemctl --user daemon-reload

# Enable DMS to start at login
systemctl --user enable dms.service

# Start DMS now
systemctl --user start dms.service

# Check status
systemctl --user status dms.service

Managing with systemd:

# Restart DMS (useful after config changes)
systemctl --user restart dms.service

# Stop DMS
systemctl --user stop dms.service

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

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
  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 (dms configuration)
    └── Connects to backend via IPC

When you run dms run, the backend server starts first, creates the IPC socket, then launches Quickshell. Quickshell connects to the backend 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, DMS processes should automatically terminate. If they don't, 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.