Environment files

Path: apis/<api>/environments/

Three kinds of file: one schema declaring the variables, one value file per environment, and an optional secrets file alongside each. Environments are discovered from the *.json files present (excluding schema.json); there's no list to maintain. See Environments for the model and resolution order.

schema.json: variable declarations

{
  "version": 1,
  "variables": {
    "baseUrl": { "description": "Base URL of the API", "type": "string", "required": true },
    "apiKey":  { "description": "API key", "type": "string", "required": true, "secret": true },
    "timeout": { "description": "Request timeout (ms)", "type": "number", "default": 5000 }
  }
}
FieldTypeRequiredDescription
version1yesFile format version.
variablesobjectyesVariable declarations keyed by name.

Each variable:

FieldTypeRequiredDescription
type"string" | "number" | "boolean"yesValue type.
requiredbooleanyesIf true, a run fails when the variable resolves to nothing.
descriptionstringnoShown in the app.
secretbooleannoIf true, values are written to *.secrets.env instead of the committed value file.
defaultstring | number | booleannoFallback value (lowest precedence).

A variable must be declared here before it can take a value.

<env>.json: values

{
  "extends": "prod",
  "level": "staging",
  "tls": { "verify": false },
  "baseUrl": "https://api-staging.example.com",
  "timeout": 8000
}

Ordinary keys are variable values. Three keys are reserved; they can't be used as variable names, and they're inherited along the extends chain (child overrides parent):

KeyTypeDescription
extendsstringParent environment to inherit from. The chain is resolved recursively, child overriding parent.
level"production" | "staging" | "local"Environment level; defaults to local. production triggers the app's confirm-before-send prompt.
tlsobjectTLS options for requests run against this environment. Only verify is read today: { "verify": false } disables certificate validation. Verification is on unless verify is explicitly false.

tls and level are set from the app, not the CLI; the env commands cover list/read/write/delete/rename. A ca key under tls is reserved for CA pinning but isn't read yet.

<env>.secrets.env: secrets

Standard dotenv. Gitignored. Follows the same extends chain as the value file.

apiKey=sk-dev-abc123xyz

Setting a value for a variable the schema marks secret: true routes it here automatically; you don't manage the split by hand.

There's no CLI to edit schema.json; declare variables in the app's environment schema editor (or edit the file directly). Values are set with craftr env write or in the app.