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 — doesn't change any state.

$ 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 currently detect version bumps (same module name, different store path). That's coming with Phase 5 — punix info which adds per-package versioning awareness.

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