Using it
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).
They speak fourteen languages. Fifteen of them carry catalogs — the disk
utility, the file manager, the package manager, the settings app, the editor,
the calendar, the terminal, the media player, the vault, the cleaner, the
sandbox, the network daemon, the arcade, the studio and the compositor — about
4,000 strings per language, following the locale with nothing to configure.
synsh keeps its own compiled-in catalog rather than using gettext, on purpose:
it runs on the ISO before /usr is necessarily complete, and a shell that
cannot find its .mo files must still be able to say why.
⚠
--recoutput never changes language, and neither does--help. A record is not writing: the first row names the columns a window parses, and the values are matched on — a vault isopenorlocked, a cleanup category isbrowsercache, a firewall isactive. The word a person reads and the word in the record are two separate strings even where they are spelled the same.--helpstays English too, in every one of them: it is a manual page in one block, with each line's text aligned to a flag spelling.The same line runs through the rest: a journal stays English because
journalctl -u synnetis what you paste into a search;[Y/n]stays[Y/n]because the script compares against those letters; and an exit status is a number in every language, which is whysyn-confine's 78 can still mean "the sandbox could not be built" rather than "the command failed".
| Command | What it does |
|---|---|
syn |
Top-level CLI — syn status, syn info, syn model/net/guard/nix … (syn net open <proto>/<port> [<cidr>] is the only verb that lets a source outside the private ranges reach a port — ⚠ allow is an unblock, not that), syn shell, syn ui, syn install, and syn game <cmd…> to launch something with the MangoHud overlay and gamemode (syn game hud on|off decides whether the overlay loads in every Vulkan client or only in what the launcher starts). See Gaming |
syn nix |
The optional Nix layer — apply, build, update, facts, edit, rollback, profile, init. Present only if you took Nix at install time; see Nix |
syn resolve |
DaVinci Resolve support — doctor, setup (OpenCL runtime and launch environment), install, transcode (rewrap footage the free edition cannot decode), launch, and gui — the DaVinci Doctor window, which walks the whole thing. See DaVinci Resolve |
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-install-gui is the same installer as a window — it writes an answer file and runs syn-install --config. --list-disks, --list-locales, --list-timezones, --list-keymaps, --list-xkb-layouts print the records either front-end renders. See Installation |
synpkg |
The package manager — search (--all searches every source at once), install, remove, upgrade, updates, installed, orphans, info, about. Other sources are subcommands: synpkg aur …, synpkg flatpak …, synpkg arsenal …, synpkg system …. synpkg tui browses in the terminal, synpkg gui [tab] opens the window. See Software |
synfiles |
The file manager — list, info, du, find, trash, copy, move, rename, mkdir, compress, undo, places, recent, volumes, mount. synfiles gui [dir] opens the window and synfiles tui [dir] browses with arrow keys in the terminal; --rec prints the records it parses. See Files |
syn-settings |
System settings — gui [pane] opens the window (display, region, time, network, bluetooth, power, apps, kernel, system); --rec <pane> prints what that pane reads, as TSV; set keymap/xkb/locale/timezone/ntp/time-format/date-format/hostname/app … changes one thing; pkg, boot and default manage kernels. -n dry-runs anything. See Settings |
syntty |
The terminal, and the default one — syntty for a shell, -e CMD to run one, --hold to keep the output after it exits, --config FILE / --no-config for the config file. See Terminal |
syn-edit |
The text editor — syn-edit file opens the terminal editor, gui the window, and run -k KEYS / ex -c CMD apply edits with no terminal at all. langs, highlight, config. See Editor |
synstudio |
The photo darkroom and video editor — probe, keys, get/set/reset a photograph's sidecar, mask, look, lut, render, match, histogram/scope, and the whole timeline … family for cutting video. synstudio gui [file] opens the window; kind FILE says what a file is. See Studio |
syn-disks |
The disk utility — drives, partitions, SMART health, mounting, safe removal, formatting and partitioning. syn-disks gui opens the window. Formatting anything that shares a disk with / is refused outright |
syn-arcade |
The game assistant — hud toggle/cycle/position/set/path/adopt drive the MangoHud overlay inside a game that is already running; pads list/info/test/rumble/calibrate/save cover controllers outside Steam; map learn/add/remove override SDL button mappings; fit new/run wraps a low-resolution game in gamescope so it fills the screen; binds install/ensure put the gaming keys in synuirc; and big start/big music …/big settings drive big screen mode, the last of them being which shelves it draws and whether it lets the screen sleep. syn-arcade gui opens the window. See Gaming |
syn-arsenal |
Browse and install BlackArch security tooling by category — a window by default, --tui in the terminal, --enable-repo to add the repository (needs root) |
syn-confine |
Run a command inside a kernel-enforced allowlist (Landlock) — --rw/--ro/--rx paths, outbound TCP denied unless a port is named, --isolate-net for no network at all, --print to see the resolved policy without running it |
syn-calc |
The calculator behind Super+X, on the command line — syn-calc 'sqrt(2) * 100'; --funcs lists what it knows. Quote the expression or the shell eats * and ( ) first |
syn-update |
Update the SynapseOS components on an installed system — check (default, read-only), apply, status. Not a replacement for synpkg upgrade, which covers Arch; see Updating |
synctl |
Talk to the running synui compositor over its control socket — synctl clients, workspaces, outputs (each monitor's geometry, scale, and the desktop it is showing — which is the only external view of a desk split by workspace_mode = per-monitor), activewindow, cursor (the pointer's layout position), recent (what has been opened, kept by the compositor at the one moment every launch has in common: a window turns up), binds (the whole bind table, each chord spelled the way a keyboard says it — this is what the welcome guide reads its key column out of), gestures (the touchpad gesture table and whether gestures are switched on), layout (the keyboard layouts xkb_layout compiled, which one is typing, and layout next / layout prev / layout <name> to move — the CLI half of the lock screen's layout chip), hdr (what each monitor will accept as an HDR10 signal, asked of the hardware without changing anything on screen — plus hdr on|off <output> and hdr white <output> <cd/m²>, the CLI half of the display panel's Shift+D), virtual (displays with no monitor behind them — virtual add <WxH[@Hz]> grows one on the running compositor, virtual mode resizes it, virtual solo <name> keeps one screen lit and turns the rest off; this is what syn-remote stream serves), dispatch <action> [arg] |
synui-welcome |
The welcome guide — toggle (the default), show [output], hide, page N. Also Super+Escape and the Welcome Guide entry in the applications menu |
syn-gfn |
GeForce NOW — no arguments opens it in the first Chromium-family browser it finds, in a profile of its own. --list-browsers says what it found and which one it would use. See Gaming |
syn-remote |
Remote desktop — on starts it now and at every login, address says how to connect, password prints the one a viewer is asked for, listen lan puts it on the network instead of loopback. wakeable on lets a magic packet wake this machine while it sleeps. Going the other way, add/trust/connect save and open somebody else's desktop — ⚠ trust is not optional, the first connection cannot complete until the certificate has been checked — and wake sends a magic packet to one, which connect also does by itself when the machine it is opening is not answering. stream on serves it to Moonlight instead — video rather than rectangles of pixels, on a display of its own that synui grows on demand and sizes to whatever the connecting client asks for; stream pair <PIN> accepts a client, and add --stream saves a Moonlight host that connect opens with Moonlight. wayvnc and sunshine are the servers; this wakes a blanked screen when somebody connects and holds the machine awake while they are there. See Remote Desktop |
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 |
The firewall
synnet is the packet filter as well as the network policy daemon. There is no
ufw and no firewalld here, and nftables.service is disabled — advice written
for another distribution will not apply.
| Command | Does |
|---|---|
synnet --status |
What the firewall is, which container bridges are trusted, and — as root — the live ruleset |
sudo synnet --firewall |
Load the input chain now, without restarting the daemon |
sudo synnet --firewall on / off |
Turn ingress filtering on or off and remember it. Off is also a switch in Settings ▸ Network |
sudo synnet --trust-if <iface> |
Accept DHCP and DNS on a container or VM bridge this machine is the gateway for — see Troubleshooting |
sudo synnet --untrust-if <iface> |
Take one back off the list |
synnet --networks |
The networks this machine is on, and which of them are trusted |
sudo synnet --trust-network <name> |
Trust a network (a saved NetworkManager connection, by name or UUID). Other devices on it can then reach this machine's services. Also Settings ▸ Network |
sudo synnet --untrust-network <name> |
Stop trusting one |
sudo synnet --open <proto>/<port> [<cidr>] |
Let one port in from a source the firewall would drop, on every network |
synnet --block <ip> / --allow <ip> |
Add or remove one address in the outbound blocklist |
The default is a default-drop input chain that accepts loopback, replies to connections this machine started, ICMP and ICMPv6, DHCP replies, anything over Tailscale, and — on a trusted network — anything from the other devices on it. On a network you have not trusted, nothing else gets in, which is what makes this laptop safe on café Wi-Fi. A network starts untrusted, and SynapseOS asks the first time you join one. Containers and VMs on this machine are not affected.
⚠ After a syn-update that brings a new synnet, restart it. pacman replaces
the binary but does not restart the unit, so the running daemon can be older than
the file on disk — and synnet --status will report on the old one.
sudo systemctl restart synnet
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, home to put a dragged one back. Visualiser, sysmon, big clock, analog clock, music, quick-launch, post-it, Tuxagotchi. See The Desktop |
Super+Shift+A |
synui-plugins |
Third-party bar widgets, in Omarchy's plugin format — browse [text] what you can install (around nine hundred community widgets; refresh fetches the list now), add <id|git-url>, <id> on|off|toggle, order <id>… to arrange them, remove, list (which says why anything is refused), check (whether what is installed can actually draw), scan. tui in the terminal, gui in a window. See Bar Plugins |
|
syn-rgb |
The wallpaper's accent on RGB hardware — on, off, status, devices, colour RRGGBB, follow accent|theme|fixed, brightness, dark. Needs openrgb |
|
synui-apply-theme |
Apply a theme across synui, the bar, GTK, Qt/KDE, the terminals (syntty, and kitty/foot where present) and Firefox |
Super+T |
synui-apply-font |
The desktop-wide text setting — --size and --scale, written to font.state and applied to every window in the suite |
Control panel ▸ Appearance |
synui-hdmi-audio |
Move audio to a screen that can take it, keyed off the ALSA ELD rather than the sink name (hdmi_audio = auto|on|off) |
Super+D |
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) — constant 60 fps to ~/Videos; --edit records a DNxHR .mov an editor reads directly, --audio[=system|mic] adds sound |
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 right-click action in Files, and in Dolphin — both read the same service menus) | — |
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. Asudo -nNOPASSWD rule, scoped to one exact command, is the deliberate substitute.
See also: Keybindings, synapd, synui.