Interface & Plugins

Customize and secure your desktop experience with these commands.

Security & Privacy

Function	Command	Description
Lock Screen	lockScreen lock	Lock your screen
Idle Inhibit	idleInhibitor toggle	Toggle idle inhibitor
Enable Inhibit	idleInhibitor enable	Enable idle inhibitor
Disable Inhibit	idleInhibitor disable	Disable idle inhibitor
Airplane Mode	airplaneMode toggle	Toggle airplane mode
Enable Airplane Mode	airplaneMode enable	Enable airplane mode (disables Wi-Fi & Bluetooth)
Disable Airplane Mode	airplaneMode disable	Disable airplane mode

Notifications

Function	Command	Description
History	notifications toggleHistory	View past notifications
Get History	notifications getHistory	Get history as JSON
Do Not Disturb	notifications toggleDND	Toggle silence mode
Enable DND	notifications enableDND	Enable silence mode
Disable DND	notifications disableDND	Disable silence mode
Clear All	notifications clear	Clear notification history
Remove Oldest	notifications removeOldestHistory	Remove oldest from history
Remove ID	notifications removeFromHistory $id	Remove notification by ID
Dismiss Oldest	notifications dismissOldest	Dismiss oldest active
Dismiss All	notifications dismissAll	Dismiss active notifications

Toast Notifications

Function	Command	Description
Send	toast send '$json'	Display a toast notification
Dismiss	toast dismiss	Dismiss active toast notification

The toast send command accepts a JSON object with the following fields:

Field	Type	Required	Description
title	string	Yes	Toast title
body	string	No	Toast body/description
icon	string	No	Icon name (only for notice type)
type	string	No	notice (default), warning, or error
duration	number	No	Duration in ms (defaults: notice=3000, warning=4000, error=6000)

Examples:

# Simple notice
qs -c noctalia-shell ipc call toast send '{"title": "Recording", "body": "Started (AV1 HDR)", "icon": "media-record"}'

# Warning toast
qs -c noctalia-shell ipc call toast send '{"title": "Low battery", "type": "warning"}'

# Error with custom duration
qs -c noctalia-shell ipc call toast send '{"title": "Connection failed", "body": "Check your network", "type": "error", "duration": 10000}'

Appearance

Visibility

Function	Command	Description
Toggle Bar	bar toggle	Toggle bar visibility
Show Bar	bar showBar	Show bar
Hide Bar	bar hideBar	Hide bar
Peek Bar	bar peek	Briefly show bar, then auto-hide
Bar DisplayMode	bar setDisplayMode <mode> <screen>	Set bar display mode
Bar Position	bar setPosition <position> <screen>	Set bar position
Toggle Dock	dock toggle	Toggle dock visibility
Show Widgets	desktopWidgets enable	Enable desktop widgets
Hide Widgets	desktopWidgets disable	Disable desktop widgets
Toggle Widgets	desktopWidgets toggle	Toggle desktop widgets
Edit Widgets	desktopWidgets edit	Toggle widget editing

Available Bar Display Modes

• always_visible
• non_exclusive
• auto_hide

<screen>: Monitor identifier (e.g., HDMI-A-1), or use an empty string or all to set mode on all monitors.

Available Bar Positions

• top
• bottom
• left
• right

<screen>: Monitor identifier (e.g., HDMI-A-1). Use an empty string or all to set position on all monitors.

Theme Controls

Function	Command	Description
Dark Mode	darkMode toggle	Toggle system theme
Set Dark	darkMode setDark	Force dark theme
Set Light	darkMode setLight	Force light theme
Color Scheme	colorScheme set <theme>	Set scheme by name
Set Method	colorScheme setGenerationMethod <method>	Set color generation method

Available Generation Methods

• tonal-spot
• content
• fruit-salad
• rainbow
• monochrome
• vibrant
• faithful
• dysfunctional
• muted

Wallpaper Management

Function	Command	Description
Selector	wallpaper toggle	Toggle wallpaper selector
Get Wallpaper	wallpaper get $monitor	Get path to wallpaper on monitor
Set Wallpaper	wallpaper set $path $monitor	Set wallpaper on monitor
Random	wallpaper random $monitor	Apply random wallpaper (omit monitor for all)
Toggle Auto	wallpaper toggleAutomation	Toggle automation
Enable Auto	wallpaper enableAutomation	Enable automation
Disable Auto	wallpaper disableAutomation	Disable automation
Refresh List	wallpaper refresh	Refresh wallpapers list

Wallpaper variables

• $path: Full path to your wallpaper image file
• $monitor: Monitor identifier (e.g., HDMI-A-1). Use an empty string or all to apply to all monitors.

Plugin Controls

Function	Command	Description
Settings	plugin openSettings $pluginId	Open plugin settings
Open Panel	plugin openPanel $pluginId	Open plugin panel
Close Panel	plugin closePanel $pluginId	Close plugin panel
Toggle Panel	plugin togglePanel $pluginId	Toggle plugin panel

Plugin ID

Replace $pluginId with the actual plugin identifier (e.g., todo, pomodoro).

Misc

Function	Command	Description
State	state all	Output settings state
Set Location	location set $name	Set geographic location
Get Location	location get	Get geographic location