Installation

konfig.ts is a workspace dependency, not a global tool. You add the CLI as a dev dependency, add the packages your manifests import, and point a konfig.json at your environment entry files.

Install the packages

Install @konfig.ts/cli as a dev dependency and the library packages as regular dependencies. Which libraries you need depends on what you render:

The binary is exposed as konfig. Run bunx konfig --help (or npx konfig --help) to confirm the install.

The Effect peer range

Every @konfig.ts/* library declares effect as a peer dependency with a caret range over the release-candidate line, currently ^4.0.0-rc.111: any rc build from rc.111 on satisfies it. @konfig.ts/core and the CLI additionally depend on @effect/platform-node at the same range, as a regular dependency rather than a peer, because they use the Node filesystem and subprocess services to write files and call helm. All packages declare engines.node >= 22.

The range is deliberately narrow: it floats across rc builds of 4.0.0 but never crosses into another prerelease line or a stable major. When Effect ships a stable 4.x, the range widens to ^4.x.

konfig.json

konfig.json tells the CLI where your sources live, which environments exist, and where rendered output goes. The commands that render (konfig build, validate, diff, and set) walk up from the current directory until they find one, and fail with ConfigNotFound otherwise. The tooling commands (konfig helm, crd, docker, and graph) do not read it. This is the file from examples/full-stack:

{
  "root": ".",
  "cluster": "infra/cluster.ts",
  "modules": "infra/modules",
  "envs": {
    "prod": { "entry": "infra/envs/prod.ts" },
    "staging": { "entry": "infra/envs/staging.ts" }
  },
  "outDir": { "manifests": ".generated/manifests" }
}

Only three fields are required: root, envs, and outDir.manifests. Decoding is strict: unknown keys, missing required keys, and invalid JSON are all reported as ConfigParseError with the file path.

The full schema accepts the fields below. Only the first five are read by a command today; the rest are accepted, defaulted, and exported as types, but no command consumes them yet.

Environment variable overrides

Four environment variables configure the Helm and CRD tooling. Precedence is: environment variable, then the matching konfig.json field, then the built-in default. The default applies when no konfig.json is found or the field is left unset; in that fallback case the path resolves against the current working directory.

Project layout

konfig.ts does not prescribe a tree, but examples/full-stack and the defaults assume this shape (the example itself has no images.json):

konfig.json              # "root": "."
images.json              # { "envs": { "<env>": { "<app>": "<image ref>" } } }, edited by `konfig set`, lives at <root>/images.json
infra/
  cluster.ts             # cluster-wide constants (domain, repositoryUrl, per-cluster overlays)
  envs/
    prod.ts              # default export: AppOfApps.fromModules({ ... })
    staging.ts
  modules/
    postgres.ts          # one Module.fixedNs / Module.dynamicNs per Application
    api.ts
  secrets/
    SopsSecret-db-creds.yaml   # encrypted secret sources read by the sops backend
.generated/manifests/    # outDir.manifests, one directory per env
.konfig/                 # cache/ (build cache, next to konfig.json) and helm-cache/, ignore in git

Two conventions matter. Each env file’s default export must be an AppOfApps.fromModules({ ... }) program, because that is what the CLI loads and runs. Each module file exports a module definition (Module.fixedNs or Module.dynamicNs) that the env file instantiates with a name, an Argo CD source, and its options.

Runtime requirements

konfig build, validate, and most other commands import() your .ts sources, so the CLI needs a runtime that executes TypeScript directly.

Next

Your first environment walks through one module, one env file, and the first konfig build.