konfig set

konfig set <env> <app> <image> records which container image an app should run in a given env. It rewrites a single entry in <root>/images.json and nothing else. It exists so a CI pipeline can promote a freshly built image with one command; a follow-up konfig build then picks the new reference up.

Usage

konfig set <env> <app> <image> [--create]

Arguments

Name	Default	Description
`env`	required	Env key in `images.json` (for example `prod`, `staging`).
`app`	required	App key under `envs.<env>`.
`image`	required	Full image reference (for example `ghcr.io/<org>/<app>:<sha>`).

Flags

Name	Default	Description
`--create`	`false`	Allow adding a new app key under an existing env. Without it, an unknown `app` fails the command instead of being added implicitly.

Behaviour

The command locates konfig.json by walking up from the current directory, then reads <configDir>/<root>/images.json. The file is parsed as JSON and decoded with a strict schema: a top-level envs object mapping env names to maps of app name to image string. Unknown top-level keys are rejected.

The command is deliberately conservative about what it will add. The env must already exist under envs; otherwise the command fails and the error lists the known env names. Adding a new env is a deliberate edit, not something set does implicitly. Likewise the app must already exist under that env unless --create is passed; an unknown app without --create fails and leaves images.json untouched. Updating an app that is already known works without --create.

On success the new config is decoded against the schema once more and written back with tab indentation and a trailing newline (JSON.stringify(cfg, null, "\t")). This matches the repo’s images.json formatting, so the resulting git diff is one line. The command logs set <env>.<app> = <image>. Nothing is rendered; run konfig build <env> afterwards.

Exit codes and errors

Error	When
`SetUnknownEnv { env, known }`	The env key is missing. Printed as `unknown env '<env>'. Known: a, b`.
`SetUnknownApp { env, app, known }`	The app key is missing and `--create` was not passed. Printed as `unknown app '<app>' in env '<env>'. Known: a, b (pass --create to add it)`.
`ImagesFileError { path, cause }`	`images.json` is missing or unreadable, is not valid JSON, or fails the schema on read or write.
`ConfigNotFound`, `ConfigParseError`	`konfig.json` cannot be found or does not match its schema.

Example

A typical CI step after pushing an image:

konfig set prod api ghcr.io/example/api:sha-${GITHUB_SHA::7}
konfig build prod
git add infra/images.json .generated/manifests/prod
git commit -m "promote api to ${GITHUB_SHA::7}"

See konfig.json for the images.json shape and for the imagesFor and requireImage helpers that read it inside modules.