Environment Variables

Crust does not introduce its own env system. Your CLI reads env from process.env, while Bun provides runtime .env loading and compiled executable behavior.

Use runtime env for secrets and deployment-specific configuration. Use build-time constants only for values that are safe to embed into the compiled output.

Runtime Env

import { Crust } from "@crustjs/core";

export const deployCommand = new Crust("deploy").run(() => {
  const token = process.env.API_TOKEN;

  if (!token) {
    throw new Error("Missing API_TOKEN");
  }

  console.log("Deploying with runtime credentials...");
});

Bun can load .env files at runtime, and compiled executables continue to use Bun's runtime env behavior. crust build does not disable that runtime loading.

Build-Time Constants

crust build follows Bun's PUBLIC_* env-prefix model for build-time constants. It can source build-time constants from Bun's auto-loaded cwd env, and it also supports explicit env files through --env-file.

crust build --env-file .env.production
crust build --env-file .env --env-file .env.local
crust build --package --env-file .env.production

• when --env-file is omitted, Bun's auto-loaded cwd env can still provide build-time constants
• the flag is repeatable
• later env files override earlier env files
• shell env still wins over env file values
• only PUBLIC_* keys are eligible for build-time constant injection

Whether values come from Bun's auto-loaded cwd env or from --env-file, only PUBLIC_* values are eligible to be embedded into the compiled output.

PUBLIC_API_ORIGIN=https://api.example.com
API_TOKEN=super-secret

Public vs Secret Values

Recommended App Pattern

For larger CLIs, centralize env handling in one config module.

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env: ${name}`);
  return value;
}

export const config = {
  nodeEnv: process.env.NODE_ENV ?? "development",
  apiToken: required("API_TOKEN"),
  publicApiOrigin: process.env.PUBLIC_API_ORIGIN,
};

Scenarios

For Bun's full runtime .env rules, see Bun environment variables and Bun single-file executables. For Crust-specific build behavior, see Building & Distribution.