Environment contracts

Use defineEnv and env builders to declare typed environment variables, defaults, required values, and secrets.

An environment contract turns process values, such as a log level or database URL, into validated application settings. Every process value starts as text; the contract parses it, applies intentional defaults, identifies secrets, and controls the values available through context.env.

defineEnv declares these settings in src/platform/env.ts. The env builders describe each field. Pass the declaration to defineApp in relkit.config.ts to make it part of your application. Declaring the contract does not read environment values; RELKIT resolves them when starting the runtime.

Declare values with defineEnv

import { defineEnv, env } from "@relkit/app/config";

export default defineEnv({
  LOG_LEVEL: env.literal("trace", "debug", "info", "warn", "error").default("info"),
});

Builders such as env.string(), env.url(), env.boolean(), numeric variants, and env.literal(...) define the accepted runtime value. Defaults are useful for harmless local policy such as log level. Credentials and other required production values should fail clearly when absent instead of receiving placeholder defaults.

env.secret() marks a value as sensitive so generated output, diagnostics, telemetry, and Inspector payloads can redact it. Secret marking is a safety boundary, not permission to log the value.

Separate environment from binding references

The contract passed as defineApp({ env }) resolves values available to application handlers. Integration configuration also uses named binding references such as binding.string(...) and binding.secret(...). Those references describe runtime wiring for an adapter; they are not additional context.env fields unless the application environment contract declares them too.

Use source-controlled configuration for stable topology and policy. Use environment values for machine-, stack-, or secret-specific data. Never place resolved credentials in source, graphs, manifests, deployment plans, or test snapshots.

Inspect configuration safely

bun run relkit env check
bun run relkit env list
bun run relkit env explain LOG_LEVEL
bun run relkit env example

check validates the active values, list reports value status without printing secret contents, explain describes one declaration, and example renders a safe template. Run bun run check after changing the contract so generated types and graph metadata stay current.

Generated commands run under Bun, which loads its normal dotenv files for the process. For one-shot and production commands, an existing process environment value takes precedence. .env.example is an informational template; RELKIT does not load it as runtime configuration. Keep its placeholder values separate from real credentials. Moving services leaves the root dotenv files in place.

During bun dev, RELKIT reloads active dotenv files for each candidate, including after a failed reload. Keys declared in those files are managed by the files: additions and edits replace startup values, and deleting a key removes its previous file-managed value. Other inherited environment values and explicit RELKIT runtime settings remain in effect.

The startup NODE_ENV selects .env.development, .env.production, or .env.test, with development as the fallback for an absent or custom value. .env.local has higher precedence and is excluded in test mode. .env.<mode>.local has the highest file precedence. Creating, deleting, or atomically replacing an active dotenv file also triggers a reload. A rejected candidate leaves the previous valid version serving until the repair succeeds; neither ordinary nor prepared startup requires restarting the CLI after a dotenv repair.

The CLI’s --environment selects the command’s provider environment. It does not turn a custom application field named RELKIT_ENV into business configuration. RELKIT owns that reserved runtime selector; the application contract continues to describe its own values.