ryoku update. When the system meets the
snapshot prerequisites it takes a snapper pre-snapshot, then brings the system
current from the signed [ryoku] repo, re-lays the base config with
ryoku materialize, and reloads the shell. There is one channel (main);
there is no channel switching, no git-pull update, and no ordered migration
ledger.
This page covers the update and snapshot model. The full ryoku command
reference — every flag for update, status, snapshots, rollback,
doctor, and recovery — lives in CLI.
What ryoku update does
On a packaged install the run is:
- Take a snapper pre-snapshot (best-effort, an unconfigured snapper never blocks the update).
sudo pacman -Syuto refresh and upgrade everything from the official Arch repos and the[ryoku]repo.yay -Sua(when yay is present) to update any AUR packages.ryoku materializeto re-lay Ryoku’s base config under~/.config, override-safe.- Reload the shell.
- Take a snapper post-snapshot.
$XDG_RUNTIME_DIR/ryoku-update.json, which
the shell’s update island reads to show the run in the pill.
ryoku update also calls ryoku doctor itself, so stateful drift gets
reconciled as part of the same run.
On a maintainer’s dev checkout the same command fetches the channel branch,
fast-forwards, and redeploys with
ryoku/shell/deploy.sh. The auto-detection
is automatic; you do not pick a mode.Status
ryoku status is read-only. It prints the active config base, the installed
ryoku-desktop version, what the [ryoku] repo offers, the count of pending
package updates (via checkupdates from pacman-contrib), and the snapshot
count.
--json form is the data seam the Hub and the update island read; it is
not meant for humans.
Snapshots and rollback
When the system meets the prerequisites, everyryoku update is wrapped in a
snapper pre/post snapshot pair. The prerequisites are a btrfs root with a
snapper root config that writes snapshots to the @snapshots subvolume at
/.snapshots. The standard ISO install sets all of this up, so on a normal
install the safety net is on from first boot.
It is best-effort by design. On a non-btrfs root, or on a machine where the
snapper root config is missing, ryoku update proceeds without a snapshot
rather than refusing to update. ryoku doctor runs inside every update and,
on a btrfs root with the root config missing, creates the config from the
same template the installer uses, registers it in /etc/conf.d/snapper,
fixes /.snapshots ownership, and enables the cleanup timer, so a drifted
or partially installed machine self-heals on the next run. On a non-btrfs
root, snapshots stay unavailable.
To see what you have:
ryoku status prints the snapshot count; ryoku snapshots lists them, and
fails clearly when snapper is not configured. If it prints The config 'root' does not exist, see Troubleshoot for the exact
recovery path.
To roll back, pass an id; with no id, ryoku rollback lists them so you can
pick one. The same snapshots are selectable from the Limine boot menu when
limine-snapper-sync is installed and snapshots exist, so a truly broken
system can be recovered from the bootloader.
sudo snapper rollback.
Self-healing: ryoku doctor
ryoku doctor runs idempotent reconcilers for the stateful drift that packages
and config cannot express. A healthy machine is quiet. It runs inside every
ryoku update, so you rarely call it by hand; ryoku doctor --check previews
what it would change without touching anything.
--check, --report, and the opt-in, read-only
--explain — see CLI. To lean on doctor while chasing a specific
problem, see Troubleshoot.
Recovery
When the desktop is too broken to update normally (a half-applied upgrade, a corrupt config, a broken local build),ryoku recovery is the last resort. It
resets to main and redeploys, overwriting configs. It hands off to
bin/ryoku-recovery, preferring a local copy and otherwise fetching the
canonical script over the network, so it still works when the local install is
broken.
Ctrl+Alt+F2), log in,
and run ryoku rollback or ryoku recovery from there. The Limine boot menu
offers the same snapper snapshots if the disk itself still boots.
Where the packages come from
The desktop ships as signed pacman packages from the[ryoku] repo
(release/packages/). ryoku-desktop is the umbrella package and depends on
ryoku-shell, ryoku-hub, ryoku, ryoku-blobs, and ryoku-keyring. The
installer adds the [ryoku] repo, imports the release key from
ryoku-keyring, and installs ryoku-desktop; from then on, ryoku update
keeps the machine current.
ryoku update upgrades installed packages. It does not pacstrap newly listed
ones, so a newly added base package reaches only fresh installs.
Because every [ryoku] package is signed and pacman verifies it on install, an
update only ever applies packages from the real release key. See
Security for how to verify releases yourself.
State the CLI keeps
The CLI keeps its state under~/.local/state/ryoku/ — deploy pointers on dev
machines, the materialized manifest of Ryoku-owned files, and the latest
doctor-report.txt. During a run it publishes live progress to
$XDG_RUNTIME_DIR/ryoku-update.json for the pill’s update island. See
CLI for the full list.
See also
- Keybindings for the shortcuts that drive the update island and Ryoku Settings.
- Troubleshoot when an update goes sideways.
- Customize for the override files updates leave alone.
- CLI for the full
ryokucommand reference. - Security for signed releases and verifying downloads.
- FAQ for quick answers on updating and rolling back.