Skip to content

punix profile

Inspect and switch user-profile generations. Every punix install and punix uninstall writes a new generation under <profile-root>'s parent>/profiles/gen-NNN/; the profile subcommands let you see the history, flip to a prior generation atomically, and diff between two generations.

punix profile list                 # enumerate generations; mark active
punix profile switch N             # atomic flip to gen-N
punix profile diff N M             # symmetric diff of installed_modules

punix profile list

Print every generation under <profile-root>'s parent>/profiles/, ascending. The active one (target of the active-profile symlink) is marked with *.

$ punix profile list
   gen-001  2026-05-27T11:13:52+00:00  just
   gen-002  2026-05-27T11:14:08+00:00  atuin, just
 * gen-003  2026-05-27T11:15:00+00:00  atuin
active: gen-003

Each line shows the generation number, the deployed_at timestamp (when this generation was written), and the comma-separated installed_modules list (or (empty) if no modules are installed in that generation).

punix profile switch N

Atomically re-point <profile-root> at gen-N. Single os.replace on the active-profile symlink: the same D9 primitive used by punix service rollback.

$ punix profile switch 1
switched to gen-001

Crash semantics (per notes/03-specs.md §20.5.1):

  • Crash before the flip returns: prior generation stays active.
  • After: new generation is active.
  • Never: a partially-flipped state. os.replace is atomic on the same filesystem.

punix profile diff N M

Set-symmetric-diff of installed_modules between two generations (read-only).

$ punix profile diff 1 3
+ atuin
- just
  • + pkg: pkg was installed in M but not in N.
  • - pkg: pkg was installed in N but not in M.
  • (no changes between gen-N and gen-M): same installed-modules set in both.

Doesn't detect version bumps: a module rebuilt at a new version has the same name in both generations, so diff reports no change even though the store paths differ. Use punix list, which parses the version out of the store path, to see which one you're on.

Common options (all subcommands)

  • --profile-root PATH: profile root (default ~/.punix/current).

Errors

Subcommand Symptom Cause
list no generations at <path> (exit 2) The profiles directory doesn't exist; no prior punix install.
switch N error: gen-NNN not found under <path> (have: …) (exit 2) Wrong generation number. The error message lists the available ones.
diff N M error: gen-NNN not found (exit 2) One of the two generations doesn't exist.

See also