keryx theme promote¶

Description¶

Copies a project theme into your user library, so every project can use it.

Themes are usually authored where the work is — in a project, against a real reel. Without promotion a good theme stays stranded there. This lifts it into your user config (spec 0046).

Usage¶

keryx theme promote <keyword> --type reel|article|portrait

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

It moves, it does not copy¶

The entry leaves the project's .keryx.yaml and arrives in your user library:

$ keryx theme promote emberlight --type reel
promoted reel theme "emberlight" to your user library
written to /home/you/.keryx/themes.yaml
moved out of /home/you/blog/.keryx.yaml — this project no longer carries its own copy

keryx theme list then shows it resolving from your library:

$ keryx theme list --type reel
reel (default: house)
  emberlight               user
* house                    user

Why moving is safe¶

A project does not need to keep a copy for CI, because CI never resolves a theme. Generation is local; CI publishes an already-generated reel, and nothing on the publish path reads the theme catalog.

(An earlier version of this page said the project kept its copy "because that is what CI reads". That was wrong — it described a pipeline that generates, which is not how keryx is used.)

If you genuinely do generate on a runner, keryx theme pin is the reverse operation: it copies a theme from your library into the project's committed config so a build with no user config can resolve it.

Ordering, and what happens if it fails¶

The library is written first; the project's entry is removed only once that succeeded. A failure between the two therefore leaves a duplicate — recoverable — rather than nothing at all. Losing a theme you spent an afternoon tuning is the outcome worth designing against.

Promoting a theme the project does not define¶

Refused. There is nothing to move, and rewriting your user copy from itself would be a confusing no-op dressed as success.

From the studio¶

Project settings → Themes shows each theme's scope, with a Promote button on project-scoped ones. It does exactly what this command does.