keryx theme add¶

Register a new theme in the catalog.

Usage¶

keryx theme add <keyword> [--from <keyword>] [--set key=value ...]

Flags¶

Flag	Description	Default	Required
`--from`	Clone an existing theme as the starting point
`--set`	`key=value`, repeatable, dotted paths allowed

There is no --type. A theme is an aesthetic, and an aesthetic has no kind — the target you are generating supplies the frame. See Themes.

What `--set` accepts¶

Dotted paths into the theme, with values coerced to bool, int or float when they parse as one and kept as strings otherwise:

keryx theme add editorial \
  --set 'palette.charcoal=#1A1D21' \
  --set 'palette.cream=#F4F1EA' \
  --set 'card.mode=overlay' \
  --set 'music.gain=0.16' \
  --set 'voice.stability=0.6'

An argument that is not key=value is rejected with invalid set (want key=value). keyword is the catalog coordinate, not a field — --set keyword=x is ignored.

Which file it writes to¶

If the working directory is inside a project that has a .keryx.yaml, the theme is written there. Otherwise it goes to ~/.keryx/themes.yaml and is available to every project on the machine. Existing comments and key order in the target file are preserved.

Use theme pin to copy a user theme into a project, and theme promote to copy the other way.

A keyword may only be used once¶

The catalog is one flat list, so a keyword identifies exactly one theme. Adding a keyword that already exists — in the project or in your user library — is refused:

$ keryx theme add editorial --set 'style=something else'
theme already exists: editorial — edit it with `keryx theme edit editorial --set …`, or pick another name

Refusing is the point. Previously the same keyword could be filed under two types, and the one you added became unreachable behind the other (keryx #12).

The first theme becomes the default¶

Keryx seeds no themes at all, so on a fresh install the catalog is empty and generation fails with no theme configured. The first theme you add becomes the default, and the command says so:

$ keryx theme add editorial --set 'palette.cream=#F4F1EA'
added theme "editorial"
set as the default theme (it is the only one)

Later additions never change the default. Adding a theme is an additive act; it must not change what an unrelated workflow resolves to (keryx #14). Use theme use to change it deliberately.