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. The first spec import writes the initial schema and environments from the spec's servers and securitySchemes; see Importing a spec.