Topgrade Wrapper

A noctalia v5 bar plugin that drives topgrade, the "upgrade everything" tool. The bar glyph shows how many packages are waiting, and the panel checks for updates and starts the run in a terminal window — so you get the pending count at a glance without giving up the interactive upgrade.

Plugin

Field	Value
ID	nightwatch75/topgrade-wrapper
Entries	Bar widget: topgrade-wrapper; panel: panel; service: service

Requirements

Noctalia v5.0.0-beta.6 or newer — the first tagged release that accepts plugin_api = 15, which the panel's settings shortcut (noctalia.openSettings()) needs — and topgrade on PATH. A terminal emulator is needed for the update run: the plugin uses Noctalia's own detection ($TERMINAL, then ghostty, kitty, alacritty, wezterm, foot, konsole, gnome-terminal, ptyxis, xterm), or the one named in the Terminal setting.

Everything else is optional and affects only the count, never the upgrade.

Count coverage

A manager is counted when the tool that can answer "how many updates?" is installed. Nothing here is required: an absent tool costs you a number, not a feature.

Counted	Needs
Arch repositories	checkupdates (from pacman-contrib)
AUR	yay or paru
Debian/Ubuntu	apt-get
Fedora/RHEL	dnf
openSUSE	zypper
Flatpak, Snap, Homebrew	flatpak, snap, brew
Cargo, npm, RubyGems, pip	cargo-install-update (from cargo-update), npm, gem, pip

Anything topgrade would run but this list does not cover — Void's xbps, Gentoo's emerge, Alpine's apk, Nix, VS Code extensions, container images, and so on — is named in the panel under Not counted, and left out of the total. A step that is only partly covered names the manager that could not answer instead: on Arch with an AUR helper but no pacman-contrib, the panel counts the AUR and lists Pacman as not counted, so the total is never mistaken for the whole system update.

Usage

Add the topgrade-wrapper widget from Noctalia's widget picker, then click it to open the panel. You can also open the panel directly or bind it in your compositor:

noctalia msg panel-toggle nightwatch75/topgrade-wrapper:panel

Action	Effect
Left click (bar glyph)	Open/close the panel
Right click (bar glyph)	Check for updates now
Check Updates (panel)	Count what topgrade would upgrade
Click a manager row (panel)	Expand or collapse the packages behind its number
Hover a package (panel)	Show its full installed → available versions below the list
Update (panel)	Run topgrade in a terminal window
Dismiss (panel)	Keep the numbers but return the bar glyph to its resting colour
↻ refresh (panel header)	Same as Check Updates
⚙ settings (panel header)	Open this plugin's page in Settings → Plugins

That settings page also opens from the command line, so it can be bound in your compositor too:

noctalia msg settings-open-plugin nightwatch75/topgrade-wrapper

The glyph turns to the accent colour with the pending count next to it once a check finds something, stays neutral while everything is up to date or after Dismiss, and turns red when topgrade is missing or a check failed. Its tooltip carries the status, the per-manager breakdown, and the time of the last check. Middle click is not used: every bar widget carries a built-in binding for it that opens the widget's own settings.

Checking

topgrade has no "how many packages?" mode, so the check runs in two stages:

1. topgrade --dry-run --no-self-update reports the steps topgrade would run. Your own topgrade configuration decides that list, which is exactly what the count needs to reflect, and the Excluded steps setting is layered on top of it.
2. Every package manager named in that output is asked once, with a read-only query, to list what it has pending — checkupdates, flatpak remote-ls --updates, and so on. The queries run one at a time.

The panel then shows one row per manager that has updates, the total in the headline, and two captions: Up to date for the managers that answered zero, and Not counted for the steps that ran but that no query covers (VS Code extensions or container images, say). A manager whose query times out or reports an error is moved to Not counted rather than shown as zero; a query that simply comes back empty is taken at its word.

Click a manager row to expand it into the packages behind its number, and click again to fold it. The number is the length of that list — the queries list rather than count, so the two can never disagree and expanding a row costs no second trip to a mirror.

Each package shows its name and, where the manager reports them, installed → available with the incoming version in the accent colour. Arch git-snapshot versions run long, so the pair is elided to fit the row; hover a package and the line under the list spells it out in full. (Noctalia's plugin UI has no tooltip for a plain row — only buttons take one — so the detail line is where the untruncated text goes. It stays visible while any list is open, hovered or not, because a line that appeared on hover would resize the list under your pointer.)

Flatpak is a special case: it tracks commits, so an app's version string often does not move across an update. When it does, the pair is shown as usual; when it does not, the short commits stand in (187a4c5 → 7a8c453) rather than an arrow between two identical numbers. Homebrew and npm report names only.

Turn Show package versions off to get plain name-only rows. The hover line stays exactly as it is with them on, so the versions remain one hover away — the setting decides how much each row carries at rest, not whether the detail is available.

Very long lists are trimmed for display, with a +N more line so the rows never quietly contradict the count. A re-check folds every row back.

Checks only happen when you ask for one, unless you set an Auto-check interval.

Updating

Update opens a terminal window running topgrade. Nothing is upgraded in the background: package managers keep their prompts, and sudo asks for your password on the terminal's tty. The window closes when the run ends unless you enable Keep the terminal open.

While the run is in flight the panel says so, and the plugin watches for the topgrade process; as soon as it is gone the counts are refreshed automatically, so the bar clears itself without another click.

Settings

Setting	Type	Default	Description
topgrade_config	file	(empty)	Alternative topgrade configuration, passed as --config. Empty lets topgrade resolve its own file.
exclude_mode	select	config	Where skipped steps come from: topgrade configuration (its disable list alone) or Override with the list below.
exclude_steps	string_list	(empty)	topgrade step ids to skip, passed as --disable <id> (e.g. flatpak, cargo, containers). Only shown, and only applied, in override mode. Run topgrade --help for the full list.
auto_check_hours	int	0	Check automatically every N hours. 0 never checks on its own.
notify_on_updates	bool	true	Send a desktop notification when a check finds packages to upgrade.
show_versions	bool	true	Show installed → available beside each package in an expanded row. Off lists names only; hovering still shows the full pair under the list either way.
terminal	string	(empty)	Terminal command for the update run, e.g. kitty. Empty uses Noctalia's detection.
assume_yes	bool	false	Pass --yes so package managers do not ask for confirmation.
sudo_loop	bool	false	Pass --sudoloop, so the password is asked once and the sudo timestamp is refreshed for the whole run.
keep_terminal_open	bool	false	Pass --keep so the window waits for a key press instead of closing.
glyph	glyph	package	The glyph shown for the widget on the bar.
show_count	bool	true	Show the pending-update count next to the glyph.

Excluding steps

By default the plugin adds nothing of its own: what topgrade skips is whatever the disable list in your topgrade.toml says, and the count follows. Switch Excluded steps source to Override with the list below to reveal the Excluded steps list and have its ids passed as --disable <id> on every command line, check and run alike. Your configuration file is never rewritten — and because --disable only ever adds, this layers on top of the config's own exclusions rather than replacing them; it cannot re-enable a step your topgrade.toml disables.

Switching the mode, or editing the list, invalidates the last count: it described a different invocation.

Ids are validated before they reach the command line, and only [a-z0-9_] is accepted; anything else is dropped with a line in the Noctalia log. An id topgrade does not know makes the check fail with topgrade's own message ("invalid value … for --disable") in the panel, which tells you what to fix.

IPC

The service accepts the same three actions as the panel buttons, so a check or a run can be bound to a key or driven from a script:

noctalia msg plugin nightwatch75/topgrade-wrapper:service all check
noctalia msg plugin nightwatch75/topgrade-wrapper:service all update
noctalia msg plugin nightwatch75/topgrade-wrapper:service all dismiss

Notes

• Commands spawned. topgrade --dry-run --no-self-update for the step list; one read-only listing query per detected manager (checkupdates, yay -Qua, paru -Qua, apt-get -s upgrade, dnf check-update, zypper list-updates, flatpak list + flatpak remote-ls --updates, snap refresh --list, brew outdated, cargo install-update --list, npm -g outdated, gem outdated, pip list --outdated, each piped through awk/sed to one package per line); and, for the run, your terminal with topgrade inside it. Nothing else, and no upgrade command is ever run outside the terminal window.
• Network. Several count queries contact package mirrors, the AUR RPC, or a Flatpak remote, exactly as the corresponding upgrade would. They are read-only and only run when a check runs.
• Privileges. The plugin never elevates anything itself. topgrade escalates per step with its own sudo_command, which prompts on the terminal's tty. Setting sudo_command = "pkexec" in your topgrade.toml routes that prompt through Noctalia's polkit agent instead, as a graphical dialog.
• Files. The plugin writes nothing: no cache, no state file, and your topgrade.toml is never modified — step exclusions are command-line overrides.
• Counts are per manager, not per step. A count is only ever as good as the query behind it, so managers without one are named instead of estimated. The total is the sum of the rows shown, nothing more.
• Settings that change the command line (the configuration file and the excluded steps) invalidate the last result, since it described a different run; cosmetic edits such as the glyph leave it alone.

Install

Install Topgrade Wrapper from Noctalia's plugin store (Settings → Plugins), then add the widget to a bar from Settings → Bar. Plugin options live in Settings → Plugins.

For local development, add your working copy as a path source instead (.luau edits hot-reload):

noctalia msg plugins source add dev path /path/to/plugins
noctalia msg plugins enable nightwatch75/topgrade-wrapper

License

MIT.