Extension settings

Use config-as-code to manage extension settings in one file per extension package. The subject is the package name. Install the extension on the target before applying its settings.

Snapshot writes one file per eligible subject, including subjects without stored values. Keep its generated filename, which is checked against subject.

Values and scopes

For an extension declaring the illustrated keys:

subject: cairncms-extension-chat-notify
global:
  sender_name: CairnCMS
  api_token:
    $secret: preserve
collections:
  articles:
    channel: editorial

Global values belong under global.<key>. Collection-scoped values belong under collections.<collection>.<key>. Install the extension with matching setting declarations on the target. A collection must already exist or be created by the same tree. It cannot be one the tree deletes.

Ordinary values are strings, numbers or booleans with the declared type. Ordinary strings may use whole-value {{CAIRNCMS_CONFIG_*}} interpolation through the CLI. Other placeholder-like text is literal, except the environment-sourced references described below.

Secrets

Source	Authored value	Apply behavior
Inline stored secret	{ $secret: preserve }	Keep the target value without copying it
Environment-sourced secret	Exact {{CAIRNCMS_EXT_*}} reference from snapshot	Supply the value through the target’s environment

Provision or rotate inline secrets through the admin app or admin API. The preserve marker does not supply a value for an unset secret.

Keep environment references exactly as emitted and configure the target environment separately. See Extension secret settings.

Omission and clearing

Removing a subject’s file stops managing that subject and leaves its values unchanged. Keeping a file makes it the complete desired set of that subject’s declared stored values. Missing keys request deletion, including inline secrets and keys present only on the target. Omitted maps mean empty desired maps.

To clear all currently declared stored values, retain the generated file with:

subject: cairncms-extension-chat-notify
global: {}
collections: {}

Review the deletion plan and authorize it with --destructive. A blank document or {} is invalid because subject is required.

This clears only currently declared stored values for that subject. It does not remove settings for uninstalled extensions, obsolete keys or environment-sourced secrets.