keryx theme migrate¶

Description¶

Moves your theme catalog out of the legacy ~/.keryx/config.yaml and into ~/.keryx/themes.yaml.

Themes used to live alongside ports, update policy and everything else. Giving the style library its own file means it can be diffed, backed up and carried between machines without dragging server settings along (spec 0042 §3.6).

Usage¶

keryx theme migrate [--dry-run]

Run keryx theme migrate --help for the authoritative, always-current flag set.

Nothing moves until you ask¶

This is a command rather than something that happens on first run. Silently rewriting two files you own, at a moment you did not choose, is the kind of surprise that erodes trust in every later write — so keryx tells you there is something to move and leaves the timing to you.

keryx doctor is what tells you:

$ keryx doctor
  [!!] Theme library: the theme catalog is still in config.yaml
       Themes now live in /home/you/.keryx/themes.yaml … Run `keryx theme migrate
       --dry-run` to see what would move, then `keryx theme migrate` to apply.

Look before you leap¶

$ keryx theme migrate --dry-run
would move 2 theme(s)
  article/clay
  reel/house
from /home/you/.keryx/config.yaml
to   /home/you/.keryx/themes.yaml

nothing was written — re-run without --dry-run to apply

Then apply:

$ keryx theme migrate
moved 2 theme(s)
  article/clay
  reel/house
from /home/you/.keryx/config.yaml
to   /home/you/.keryx/themes.yaml

What it does and does not touch¶

Only the themes subtree moves. Your config.yaml keeps its other job — ports, update policy, git behaviour — untouched.
Per-type defaults ride along, so commands keep resolving a theme without --theme. A library with themes but no defaults would make every command need one.
A theme already in your library is left alone. If you promoted it from a project after the legacy copy was written, the library holds the newer version, and overwriting it with a stale duplicate would undo deliberate work.
The library is written first, and the legacy entries removed only once that succeeded — so a failure leaves a recoverable duplicate rather than nothing.

You do not have to run it immediately¶

An unmigrated catalog keeps working: keryx reads the legacy file as a lower-precedence layer, so themes resolve either way. Migrating is what stops the old file being the real home.