Software

Software

synpkg is SynapseOS's package manager — one program over the five places software on this system comes from. It is a single C binary built on libalpm (the library pacman itself uses), with three front-ends that all read the same code paths, so they cannot disagree about what is installed:

Front-end	Command
Graphical browser	Software Manager in the start menu, or synpkg gui
Terminal browser	synpkg tui (or bare synpkg on a terminal)
Command line	synpkg search, synpkg install, …

It works over SSH and on a headless machine — the GUI is an optional extra, and each front-end degrades to the one below it rather than failing.

---

The five sources

Every source gets its own tab in the GUI, and every row carries a coloured badge naming where it came from. That is deliberate: these are not interchangeable, and installing from one is not the same act as installing from another.

Tab	What it is	What actually installs it
Repositories	Arch's core, extra, multilib, plus SynapseOS's own [synapseos]	pacman. Signed binaries, built by Arch or by us.
AUR	The Arch User Repository — build recipes, not binaries	makepkg, on your machine. Opens a terminal so you can read the PKGBUILD first.
Flathub	Sandboxed applications shipping their own runtimes	flatpak, with its own permission prompts. Installed alongside your system, not into it.
Arsenal	~5000 BlackArch security tools, browsable by category	pacman, once the BlackArch repo is enabled.
SynapseOS	This system's own components	syn-update, which rebuilds them from git. See Updating.

Two of these are off until you turn them on. A source that is switched off looks exactly like a source with nothing in it, so synpkg about reports the state of each one, and the GUI offers a button where the fix is a command.

synpkg about                     # which sources are wired up on this machine
synpkg flatpak enable-flathub    # add the Flathub remote and fetch its index
synpkg arsenal enable-repo       # bootstrap BlackArch (keys, mirrors)

Enabling Flathub also downloads its application index. Without that index flatpak search returns nothing and reports no error — which reads as "Flathub is empty" rather than "this is not ready yet". enable-flathub does both steps so that cannot happen to you.

---

Everyday use

synpkg search firefox        # the repositories
synpkg install firefox
synpkg remove firefox        # takes its unneeded dependencies with it
synpkg upgrade               # full system upgrade (refreshes first)
synpkg updates               # what an upgrade would change, read-only
synpkg installed --explicit  # what you asked for, as opposed to what came along
synpkg orphans --remove      # dependencies nothing needs any more
synpkg info firefox

Other sources are subcommands, so the source is always visible in what you typed:

synpkg aur search <term>         # and: aur install, aur installed, aur updates
synpkg flatpak search <term>     # and: flatpak install/remove/updates/remotes
synpkg arsenal categories        # and: arsenal packages <category>, arsenal installed
synpkg system check              # SynapseOS's own components (via syn-update)

synpkg upgrade is the same engine pacman -Syu is, and pacman keeps working — use whichever you prefer. Both refresh the databases before they upgrade, which is what stops you from ending up with a partial upgrade: a system whose package databases are newer than its packages, where every later install fails on a filename the mirror has already rotated away.

Exit codes

Every list command returns 100 for "nothing to do", distinct from 1 for failure — so a status bar or a script can tell "you are up to date" from "the check broke" without parsing any output.

---

The graphical browser

Software Manager in the start menu, or synpkg gui. synpkg gui <tab> opens straight onto one tab (updates, suggested, repo, aur, flathub, arsenal, system, about).

• Updates is the union of all three updatable sources — repositories, AUR and Flathub — with each row badged, so you can see at a glance which half of the system is behind.
• Suggested is a curated list of applications worth having, grouped by category, with the ones you already have marked.
• Repositories, AUR and Flathub each have a Search and an Installed view.
• Arsenal lists BlackArch by category, plus an "Installed tools" view — so a tool can be removed without remembering which of ~50 categories it came from.
• About reports what is enabled and offers to fix what is not.

Two things happen in a terminal rather than in the window, on purpose:

• A full system upgrade. It downloads for minutes and prints as it goes; a window with a spinner and no output is where people force-quit mid-transaction.
• Any AUR install. An AUR package is arbitrary code that builds on your machine. synpkg shows you the PKGBUILD and asks before running makepkg, which needs a terminal to ask in — and which refuses to run as root, correctly.

Everything else escalates through polkit when it needs to, so the GUI itself never runs privileged.

---

Flatpak notes

Flatpak applications are identified by an application id — org.mozilla.firefox, not firefox. The GUI shows the human name with the id beside it; the command line takes the id.

synpkg flatpak search boxes
synpkg flatpak install org.gnome.Boxes
synpkg flatpak remotes           # which remotes are configured

Anything synpkg does not wrap is passed through to flatpak unchanged, so synpkg flatpak permissions <id> works without needing us to have thought of it.

---

See also

• Updating — the SynapseOS half of keeping current
• Commands — the whole command-line surface
• Building and Packaging — building components yourself