Presets

Presets are versioned variable bundles an app publishes so an operator can install a known-good configuration by name instead of setting individual --vars. They power the install-time catalog:

shc install wordpress --preset woocommerce
shc install wordpress --preset woocommerce@latest

Source: modules/app/preset.go (schema + resolution) and modules/app/preset_loader.go (catalog loading). The read-only CLI over the catalog is shc preset.

Files

File	Scope
`apps/<name>/preset.yaml`	presets for the app itself (applied via `shc install <app> --preset …`)
`apps/<name>/<vapp>.vpreset.yaml`	presets for one vapp, next to its `<vapp>.vapp.yaml`

Both files share the same shape: a map keyed by preset name.

Format

small:
  meta:
    description: "Small instance"
    homepage: https://example.com
    category: sizing
    tags: [small, starter]
  default: "1.0"
  versions:
    "1.0":
      worker_count: 1
    "2.0":
      worker_count: 2
  aliases:
    stable: "1.0"
  vars:
    tls: true

Key	Meaning
`meta`	display metadata: `description`, `icon`, `homepage`, `category`, `tags` — all optional; `tags`/`category` feed `shc preset search` filters
`vars`	base variables applied for every version
`versions`	per-version variable overlays, keyed by version string
`default`	the version picked when the operator names no `@<version>`
`aliases`	alternate names for version keys (e.g. `stable: "1.0"`)

A preset may be versionless (just vars, no versions block) — then requesting an explicit @<version> is an error.

Resolution

--preset NAME[@VERSION] resolves in this order:

Version pick — the explicit @<version> if given, else the preset’s default (a preset with versions but no default requires an explicit version). aliases are dereferenced, and the special version latest picks the highest semver-ordered key.
Merge — vars (base) ⊕ versions[<resolved>] ⊕ any operator --var overrides, later layers winning.
Persist — the resolved version key is recorded in the deployment state so re-renders and upgrades stay symmetric.

Failures surface as X400048PRSVRN (unknown/ambiguous version) with the available version list in the message.

Inspecting presets

shc preset ls <app>                    # everything the app ships
shc preset show <app> NAME[@VERSION]   # resolved var map
shc preset versions <app> NAME         # version keys
shc preset search <query>              # cross-catalog search

See the shc preset CLI reference for flags and the remote-search behavior.