Environments

Kulala resolves variables from several sources. Understanding the order helps avoid surprises.

Resolution order

Later sources override earlier ones:

1. @name=value lines in the .http file (file header and block preamble)
2. http-client.env.json and http-client.private.env.json (merged upward from the working directory; closest file wins)
3. .env files (optional, less flexible than JSON)
4. Persisted variables (global → document → request scope)
5. Magic variables ($uuid, $timestamp, …)

http-client.env.json

Define named environments (dev, staging, prod, …) and Kulala extensions:

{
	"$schema": "https://kulala.app/http-client.env.schema.json",
	"$kulala": {
		"defaults": {
			"headers": {
				"X-Kulala-Shared-Default-Header": "kulala-family"
			},
			"curlOptions": ["--insecure", "--max-time 0.01"]
		},
		"env": {
			"API_URL": "https://echo.kulala.app"
		}
	},
	"default": {
		"env_name": "default"
	},
	"dev": {
		"env_name": "dev"
	},
	"staging": {
		"env_name": "staging"
	},
	"prod": {
		"$kulala": {
			"defaults": {
				"headers": {
					"X-Kulala-Default-Header-in-Prod": "kulala-family"
				},
				"curlOptions": ["--no-insecure", "--max-time 1"]
			}
		},
		"env_name": "prod"
	}
}

Reference env-file variables directly: {{API_URL}}, {{env_name}}.

Headers and curl options merge from top-level $kulala.defaults, then the selected environment’s $kulala.defaults (the environment wins per header). $kulala inside an environment only holds defaults and is not a variable. Variables for every environment live in $kulala.env; variables for one environment stay as direct keys on that environment. $schema and $kulala are not environment names.

Store secrets in http-client.private.env.json (add it to .gitignore). Private values override the public file for the same environment key.

System environment variables

Important: process environment variables use the JetBrains form {{ $env.VAR }}, not plain {{VAR}}:

POST https://echo.kulala.app/post HTTP/1.1
Content-Type: application/json

{
  "kuba_env_test": "{{ $env.API_BEARER_TOKEN }}",
  "OS_USER": "{{ $env.USER }}"
}

Plain {{USER}} does not read from the OS environment - only {{ $env.USER }} does. See Migration.

Kuba

When a kuba.yaml is found in a parent directory, Kulala runs kuba show and exposes values as {{ $env.KEY }} (same prefix as system env):

GET https://echo.kulala.app/get HTTP/1.1
Authorization: Bearer {{ $env.API_BEARER_TOKEN }}

OAuth 2.0 tokens

OAuth profiles are configured in http-client.env.json / http-client.private.env.json. Use {{$auth.token("profile-name")}} in requests - see Authentication.