The pulsar command
Themes, health checks, changes, agents and rollback, in one command.
Everything it does
pulsar -- manage a Pulsar system
Health
pulsar doctor [check] health checks; exit 1 if one fails. the default
command. see: pulsar doctor --help
pulsar status deployments: booted, staged, rollback, pins
pulsar report a diagnosis bundle to paste: doctor, status,
manifest, failed units, recent warnings, graphics,
Flatpak. JSON; --text for people. redacted
pulsar crashes this boot's crashes. ignore list | add | remove:
programs whose crashes are not announced
This image
pulsar manifest what is in this image, and what it runs on
pulsar changelog packages that moved in the latest published build
pulsar sbom this system's packages as SPDX 2.3
pulsar verify check the running image's signature
Updates and undo
pulsar update fetch and stage the newest image (root)
pulsar update --check is a newer image published? exit 10 if so
pulsar rollback boot the previous deployment next (root)
pulsar pin [on|off] keep the booted deployment through GC (root)
pulsar checkpoint snapshot /etc, your settings and pin, (root)
to diff or restore later:
list | diff | restore | drop
Desktop
pulsar theme <command> recolor the whole desktop: list | set <theme> |
revert | ...
pulsar setup <recipe> apps | devbox | gamemode | quadlet | gamescale
Agents
pulsar agent what this machine gives a coding agent:
guide | list | add | remove | default | run |
sandbox [on|off] | guard [on|off]
pulsar agent model on a local model for agents, on this machine's GPU
pulsar agent ask start your agent on a redacted report of this
machine; --crash latest for the last crash
pulsar mcp this machine's facts as MCP tools, for any agent
(agent add registers it). nothing in it needs root
Options
--json JSON output, anywhere on the line. A command
without it says so rather than print text.
`manifest --json` puts host facts under "host", so
`jq 'del(.host)'` is the baked manifest
--logo, --no-logo force or suppress the mark in `manifest`
--version, --help pulsar help <command> for one command
Plain pulsar runs doctor. pulsar help <command> or
--help shows a command’s usage. Only commands marked root need it.
| Commands | Explained in |
|---|---|
doctor, report | Troubleshooting |
status, update, rollback, pin, checkpoint | Updates and rollback |
theme | Themes |
agent, mcp | Coding agents |
setup | Where things go |
manifest, changelog, sbom, verify | Provenance |
For scripts
--json works anywhere on the line; commands without JSON output exit with an error.
doctor exits 1 only on a failed check; update --check exits 10 when an
update is available.
pulsar doctor --json | jq -r '.checks[] | select(.status != "ok") | .summary'
pulsar update --check --json # {status, booted, latest, image, staged}
pulsar manifest --json | jq 'del(.host)' # the manifest baked into the image
setup: what the image can’t include
Each setup recipe handles per-machine or per-account state (apps, groups,
containers) and tells you if it needs, or must not have, sudo.
sudo pulsar setup apps # install any default Flatpak that is missing
pulsar setup devbox # a dev distrobox, pulsar-dev, from /usr/share/pulsar/distrobox.ini
sudo pulsar setup gamemode # enroll accounts in the gamemode group
pulsar setup quadlet # the quadlet template, and container auto-update
pulsar setup gamescale --platform <name> # gg and gamescale for a Flatpak launcher other than Steam
Where things go · gamescale setup
How doctor checks
doctor reads actual system state (e.g. /sys/kernel/sched_ext/state),
not unit status, and needs no root: it reads through rpm-ostree, not
bootc status. pulsar sbom is generated from the live rpm database with
the nightly’s script.
update, not upgrade
bootc upgrade drops packages layered with rpm-ostree install.
pulsar update uses rpm-ostree upgrade when you have layers (see
doctor’s updates line). pulsar update --check needs no root.
Updates.
If a different pulsar runs
The Pulsar code editor’s RPM or AppImage can shadow this pulsar on
PATH (its Flatpak doesn’t). /usr/bin/pulsar always works; doctor’s
cli check flags shadowing.
The source is cli/pulsar, one shell script.
Written with help from AI and reviewed by a person before publishing. Spotted a mistake? Let us know.