Skip to content
varlock

Usage

Basics

Section titled “Basics”

The basic workflow for using Varlock is to:

  1. Run varlock init to set up your .env.schema file
  2. Run varlock load to debug and refine your .env file(s)
  3. Use Varlock to load, validate, and inject env vars into your application, either:
    • Use an existing framework / tool integration that automatically calls Varlock under the hood (recommended)
    • Use import 'varlock/auto-load' in a backend JavaScript/TypeScript project
    • Boot your command via varlock run
      (necessary for non-JS/TS projects, or feeding env vars to external tools)

CLI Commands

Section titled “CLI Commands”

varlock load

Section titled “varlock load”
Terminal window
npm exec -- varlock load

Validates your environment variables according to your .env.schema and associated .env.* files, and prints the results.

Useful for debugging locally, and in CI to print out a summary of env vars, also when you’re authoring your .env.schema file and want immediate feedback.

See the varlock load CLI Reference for more information.

Understanding varlock load output

Section titled “Understanding varlock load output”

By default, varlock load prints a human-readable summary to stdout. Schema and validation errors go to stderr first; if loading succeeds, you will see a -- Resolved config -- header followed by one block per item.

For example, given a schema like this:

.env.schema
# @defaultRequired=false
# @defaultSensitive=false
# ---
# @required
SERVICE_NAME=payments-api
LOG_LEVEL=info
# @type=number
PORT="8080"
# @type=boolean
FEATURE_FLAG_BETA="true"
# @required
APP_ENV=development
# @sensitive @required
DATABASE_URL=postgres://user:pass@localhost:5432/app
# @sensitive
SESSION_SECRET=cache(randomHex(32), ttl="1h")
# @sensitive @required
STRIPE_SECRET_KEY=

varlock load prints (with STRIPE_SECRET_KEY set in .env, APP_ENV overridden in the shell, and SESSION_SECRET served from cache on a second run):

Terminal window
-- Resolved config --
✅ SERVICE_NAME*
   └ "payments-api"
✅ LOG_LEVEL
   └ "info"
✅ PORT
   └ 8080 < coerced from "8080"
✅ FEATURE_FLAG_BETA
   └ true < coerced from "true"
✅ APP_ENV*
   └ "production"  🟡 process.env
✅ DATABASE_URL*  🔐sensitive
   └ po▒▒▒▒▒
✅ SESSION_SECRET  🔐sensitive
   └ df▒▒▒▒▒  📦 2m ago
✅ STRIPE_SECRET_KEY*  🔐sensitive
   └ sk▒▒▒▒▒

Each item line shows:

  • A status icon (✅ valid, or an error/warning icon if something failed)
  • The key name, with * if @required
  • 🔐 sensitive when the item is marked @sensitive — values are redacted in the summary
  • The resolved value (quoted strings, colored booleans/numbers)
  • Inline hints such as 📦 (cached), 🟡 process.env (overridden by the shell), or < coerced from ... when a value was coerced

When validation fails, only failing items are shown unless you pass --show-all. Use --format json or --format json-full for machine-readable output. For example, in CI or when piping to other tools.

For example, with STRIPE_SECRET_KEY left empty:

Terminal window
🚨🚨🚨  Configuration is currently invalid  🚨🚨🚨


❓ STRIPE_SECRET_KEY*  🔐sensitive
   └ undefined
   - Value is required but is currently empty


💥 Resolved config/env did not pass validation 💥

varlock run

Section titled “varlock run”
Terminal window
npm exec -- varlock run -- <your-command>

Executes a command in a child process, injecting your resolved and validated environment variables. This is useful when a code-level integration is not possible. For example, if you’re using a database migration tool, you can use varlock run to run the migration tool with the correct environment variables. Or if you’re using a non-js/ts language, you can use varlock run to run a command and inject validated environment variables.

See the varlock run CLI Reference for more information.

varlock encrypt

Section titled “varlock encrypt”
Terminal window
npm exec -- varlock encrypt --file .env.local

Encrypts sensitive values using device-local encryption. Use --file to encrypt all @sensitive plaintext values in a .env file in-place, or run without arguments for interactive single-value encryption.

Encrypted values are stored as varlock("local:<encrypted>") and are automatically decrypted during varlock load or varlock run.

See the varlock encrypt CLI Reference and the Local encryption guide for more information.

varlock reveal

Section titled “varlock reveal”
Terminal window
npm exec -- varlock reveal

Securely view or copy decrypted values of @sensitive environment variables. Values are shown in an alternate screen buffer to prevent scrollback capture.

See the varlock reveal CLI Reference for more information.

Come chat with us

© 2026 DMNO Inc. All rights reserved.