Declarative configuration

cademi config manages part of your account as code: you describe the desired state in a manifest, check it, review the plan of changes, and apply it. The CLI accepts manifests in YAML or JSON and runs the validation, plan, and application flow of the API.

The manifest

A manifest uses the cademi/configuration-manifest/v1 format. In YAML:

$schema: cademi/configuration-manifest/v1
resources:
  - kind: product
    ref: course-a
    external_id: erp-123
    attributes:
      name: Course A
      status: published
  - kind: module
    ref: mod-1
    attributes:
      name: Module 1
      product: { $ref: course-a }
  - kind: webhook
    ref: erp
    id: whk_01J8Z3...
    attributes:
      url: https://erp.example/hook
      secret: whsec_...
  - kind: banner
    ref: old
    id: ban_01J8Z2...
    $delete: true

Files ending in .yaml or .yml are read as YAML, and any other file as JSON. Pass - to read the manifest from standard input, in either format. The CLI converts YAML to JSON before sending it, so both formats follow the same rules.

The supported kinds, identity rules (ref, id, external_id), references ($ref), explicit deletion ($delete), ordered sets, and limits are described in Declarative configuration. Existing resources that the manifest omits are never deleted.

Validate

cademi config validate catalog.yaml

Validation changes nothing. The command prints each error and warning with its path, message, and code, confirms when the manifest is valid, and lists the permissions that applying it would require. It exits with code 6 when the manifest is invalid. The credentials need configuration.validate.

Plan

cademi config plan catalog.yaml
cademi config plan catalog.yaml --out plan.json

The plan compares the manifest with the account and changes nothing. The CLI prints the plan ID and its expiration, then one line per step, with the kind, the ref followed by the resource ID or external_id when there is one, and the action: + create, ~ update, - delete, = no change, and ! skip with its reason. Below each step, it lists the fields that change, from the current value to the new one. A summary line counts the steps to create, update, delete, leave unchanged, and skip.

--out saves the plan as JSON, to review it or apply it later. A plan is valid for 24 hours, can be applied once, and only with the credentials that created it. The credentials need configuration.plan.

If the manifest is invalid, the API creates no plan, and the command exits with code 6.

Apply

cademi config apply catalog.yaml

apply computes the plan, prints it, asks for confirmation, and applies it. The API applies the plan as an asynchronous operation, one item per step, and the command waits for it to finish, printing its progress. The credentials need configuration.apply.

When the account already matches the manifest, the command says so and applies nothing.
--yes (-y) skips the confirmation. Without a terminal, apply fails with exit code 2 unless you pass --yes. When the profile is a production profile, the question starts with [production].
--no-wait returns as soon as the operation is created. Follow it with cademi operations wait <operation_id>.
If the operation does not end as succeeded, the command exits with code 1. Steps that were already applied stay applied: run cademi config apply again to compute a new plan and converge.

To apply a plan you saved, pass it with --plan:

cademi config plan catalog.yaml --out plan.json
cademi config apply --plan plan.json catalog.yaml

The API rejects a saved plan that expired (409 plan_expired), that was already applied (409 state_conflict), or that no longer matches the account because a resource changed after planning (409 plan_stale), and the command exits with code 6. In each case, compute a new plan.

Secrets

Secrets in the manifest, such as webhook.secret and write-only settings fields, are never printed: the plan and the saved plan file show them as ***. When you apply, the CLI replaces each *** with the real value from the manifest, matching the step by its ref. For that reason, cademi config apply --plan still needs the manifest when the plan contains secrets. If a secret has no value in the manifest, the command stops before applying anything and exits with code 2.

Keep manifests that contain secrets out of version control, or protect them like any other secret file.

The underlying operations

cademi config combines three API operations, which are also available as regular commands: cademi configuration validations create, cademi configuration plans create, and cademi configuration applications create. Use them when you need the raw responses.