keryx theme pin¶

Description¶

Copies a theme from your user library into this project's .keryx.yaml.

A build runner has no user config, so a project that must build unattended has to carry the themes it uses. Pinning makes that dependency explicit and committable (spec 0046).

It is the mirror of keryx theme promote.

Usage¶

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

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

Why you need it¶

Themes resolve from two scopes: your user config, and the project's committed .keryx.yaml. Locally you see both. CI sees only the project's — so a reel whose theme lives in your library builds on your machine and fails on the runner.

$ keryx theme pin neon --type article
pinned article theme "neon" to this project
written to /home/you/blog/.keryx.yaml
commit it so CI resolves the same theme you do

Commit the change and the project is self-contained.

It copies, and the project's copy wins¶

Your library keeps its own copy — pinning adds a second one that travels with the repo. From then on the theme is defined in both scopes, and inside the project the pinned copy wins. keryx theme list shows which scope each theme resolves from.

That is deliberate: the committed copy is the one CI uses, so it should be the one you see locally too. Otherwise a build could differ from your preview because your library had drifted.

Re-pinning¶

Running it again refreshes the project copy from your library, which is how you take a later change to a theme into a project.

Note this reads your user version specifically, not the resolved one — the pinned copy shadows it, so copying the resolved theme would write the project's own version back over itself and change nothing.

Pinning a theme your library does not define is refused: a project-only theme is already where CI needs it.