Commands

Commands

The command-line surface of SynapseOS, and the short list of privileged actions the desktop is allowed to run without a password.

---

Command-line tools

Every tool is prefixed syn and self-documents with --help (or help).

Command	What it does
syn	Top-level CLI — syn status, syn info, syn model/net/guard …, syn shell, syn ui, syn install
synsh	Natural-language shell — type plain English or normal commands; --no-ai for pure shell, --intent-check to test an intent
syn-model	Model manager — download [mistral-7b|phi3|tiny], list, status, remove
syn-install	Install SynapseOS to disk (the live-ISO installer)
syn-update	Update the SynapseOS components on an installed system — check (default, read-only), apply, status. Not a replacement for pacman -Syu, which covers Arch; see Updating
synctl	Talk to the running synui compositor over its control socket — synctl clients, workspaces, outputs, activewindow, dispatch <action> [arg]
syn-crypt	Manage LUKS2 disk encryption on an installed system — status, add-key, change-key, remove-key, backup-header
syn-secureboot	Enroll Secure Boot keys (checks for real Setup Mode first — see Secure Boot)
synui-ai-backend	Switch synapd's inference device — gpu / cpu / off / toggle / status (see synapd)
synapd · synguard · synnet · synui	The daemons and compositor — normally started by systemd, not by hand

Desktop helpers

These are the command-line side of the synui panels. In every case the panel and the keybind run the command rather than writing state themselves, so there is one format and one place a setting can be wrong.

Command	What it does	Panel
synui-sound	Event sounds — <event> on|off, test, theme, sound, volume, install, remove. See Sound Themes	Super+S
synui-cursor	Cursor themes — list, current, install, build, set. See Cursor Themes	Super+Shift+P
synui-widgets	Desktop widgets — <widget> on|off|toggle, all off. See The Desktop	Super+Shift+A
synui-apply-theme	Apply a theme across synui, the bar, GTK, Qt/KDE, the terminal (kitty, and foot where present) and Firefox	Super+T
synui-wpengine	Steam Workshop wallpapers — list, set <id> [output|all], off [output|all], restore, status. See Wallpapers	Super+W
synui-glass · synui-firefox-glass	Window glass; the Firefox one also sets/reverts browser.tabs.allow_transparent_browser	Super+E
synui-screenshot	region / full — to ~/Pictures/Screenshots and the clipboard	Print
synui-record	Start / stop screen recording (wf-recorder)	Super+Shift+R
synui-clock	Formats the clock for the bar and the BigClock widget	Super+Shift+T
synui-game-run · synui-game-status	Launch wrapper (MangoHud/gamemode/gamescope) and indicator — see Gaming	Super+G
synui-wine-run	Run-with-Wine wrapper (also a Dolphin context-menu action)	—
synui-iso-mount · synui-iso-write	Mount an ISO (udisks2, no root) / write one to a USB stick	—
synui-bar	Launch the quickshell bar	—

synui-wpengine is the one helper that does not ship with synui — it comes with the linux-wallpaperengine package, which is on the ISO as of 0.2.1.

Two of these install untrusted archives off the internet — synui-cursor install and synui-sound install. Both re-resolve every extracted path against the extraction root and refuse anything that escapes it, and neither ever runs anything from the archive. synui-cursor build, which does run the archive's own makefile, is a separate command that prompts first.

Check the daemons and kernel module:

systemctl status synapd      # AI inference daemon
systemctl status synguard    # security monitor
systemctl status synnet      # network policy
lsmod | grep synapse_kmod    # kernel module
cat /sys/kernel/synapse/status

---

Privileged desktop actions (sudo -n)

synui runs as the session user — under a greetd session it is not root — and the target has no polkit agent to prompt for a password. So the handful of desktop actions that genuinely need root are granted passwordless through tightly-scoped /etc/sudoers.d rules (written by syn-install). Each helper self-escalates with sudo -n, and these are the only commands %wheel may run without a password:

Command	Rule file	Triggered by
sudo -n systemctl reboot · poweroff	power-menu	Start-menu Reboot / Shut Down
sudo -n systemctl stop synapd · start synapd	synapd-gamemode	Game mode (Super+G) frees the GPU
sudo -n synui-ai-backend gpu|cpu|off|toggle	synapd-backend	"AI backend" row (control panel / Super+Escape)

Everything else still prompts for a password (%wheel ALL=(ALL:ALL) ALL). When synui instead runs as root via synui.service, the sudo -n re-exec is a no-op — the helpers already hold the privilege they need.

Why not polkit? There is no authentication agent in the session (see Troubleshooting), so an interactive pkexec/polkit prompt would hang with nothing to answer it. A sudo -n NOPASSWD rule, scoped to one exact command, is the deliberate substitute.

See also: Keybindings, synapd, synui.