Running Apps

run, gen, check. Three commands, most of what you'll actually use day to day.

run

npx dotvars run --env <env> [--param key=val] -- <command> [args...]

Decrypts config.vars for the given env and injects the values into a child process. Nothing touches disk. Secrets exist only in that process and are gone when it exits.

# Start your dev server with dev secrets
npx dotvars run --env dev -- npm run dev

# Run a script with prod secrets
npx dotvars run --env prod -- node scripts/migrate.js

# Override a single value at runtime
npx dotvars run --env prod --param DATABASE_URL=postgres://localhost/mydb -- node scripts/migrate.js

vars also sets VARS_ENV in the child's environment so your app knows which env it's running under.

Flags

The -- separator is required. Everything after it is the command vars runs.

gen

npx dotvars gen <file>

Generates a typed TypeScript file with accessor functions for every variable in a config.vars file. No key needed — gen works on locked files by reading schemas without decrypting values. Import the generated file instead of reading process.env directly and you get autocomplete and type safety.

# Generate types for the default config.vars
npx dotvars gen config.vars

# Generate for all entry points at once
npx dotvars gen --all

# Write to a custom output path
npx dotvars gen config.vars --output src/lib/env.ts

Flags

hide reruns gen automatically if your schemas changed since the last run, so you won't call this often.

Platform Targets

By default, vars gen creates code that reads from process.env (Node.js). For other platforms, use the --platform flag:

Node.js (default)

vars gen config.vars

Generated code: export const vars = parseVars(process.env)

Works with: Next.js, Express, Hono (Node), Fastify, any Node.js server.

Cloudflare Workers

vars gen config.vars --platform cloudflare

Generated code: export function getVars(env) { return parseVars(env) }

Workers don't have process.env. Pass the env bindings from your handler:

import { getVars } from '#vars'
import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => {
  const vars = getVars(c.env)
  return c.json({ app: vars.APP_NAME })
})

Deno

vars gen config.vars --platform deno

Generated code: export const vars = parseVars(Deno.env.toObject())

Static (inlined values)

VARS_KEY=$KEY vars gen config.vars --platform static --env prod

Generated code bakes decrypted values directly into the file — no process.env, no runtime resolution:

export const vars = {
  APP_NAME: "my-app",
  PORT: 3000,
  DATABASE_URL: new Redacted("postgres://prod.db/myapp"),
}

Use this for: Edge functions, Vite client bundles, any context where process.env is not available. Requires the encryption key at gen time. Regenerate per environment at build time.

Important: The static file contains decrypted secrets. Only use it for server-side builds, never commit it to git. Add it to .gitignore.

check

npx dotvars check [file]

Validates every env against your Zod schemas, runs any check blocks defined in the file, and reports expired or deprecated variables. No --env flag means all envs get checked.

# Validate all envs in config.vars
npx dotvars check config.vars

# Validate staging only
npx dotvars check config.vars --env staging

# Validate all vars files in the project
npx dotvars check --all

It checks:

• Missing required values
• Schema conformance (shows expected vs. got on failure)
• Expired secrets (errors on past expiry, warns if expiring within 30 days)
• Deprecated variables still in use
• check blocks defined inline in the vars file
• @refine cross-variable validations

Exits 1 on errors. Encrypted values that can't be decrypted in the current context are skipped.

Flags