CLI Commands

Varlock provides a command-line interface for managing environment variables and secrets. This reference documents all available CLI commands.

See installation for instructions on how to install Varlock.

Running commands in JS projects

If you have installed varlock as a package.json dependency, rather than a standalone binary, the best way to invoke the CLI is via your package manager:

npm exec -- varlock ...

pnpm exec -- varlock ...

bun exec varlock ...

vlx -- varlock ...

yarn exec -- varlock ...

Also note that within package.json scripts, you can use it directly:

{
  "scripts": {
    "start": "varlock run -- node app.js"
  }
}

`package.json` configuration

You can configure varlock’s default behavior by adding a varlock key to your package.json:

{
  "varlock": {
    "loadPath": "./envs/"
  }
}

Option Description

loadPath Path (or array of paths) to a directory or specific .env file to use as the default entry point. Defaults to the current working directory if not set. Use a directory path (with trailing /) to automatically load all relevant files (.env.schema, .env, .env.local, etc.); a file path only loads that file and its explicit imports. When an array is provided, all paths are loaded and combined — later entries take higher precedence. Can be overridden by the --path CLI flag. Varlock looks for this config in the package.json in the current working directory only.

Option	Description
`loadPath`	Path (or array of paths) to a directory or specific `.env` file to use as the default entry point. Defaults to the current working directory if not set. Use a directory path (with trailing `/`) to automatically load all relevant files (`.env.schema`, `.env`, `.env.local`, etc.); a file path only loads that file and its explicit imports. When an array is provided, all paths are loaded and combined — later entries take higher precedence. Can be overridden by the `--path` CLI flag. Varlock looks for this config in the `package.json` in the current working directory only.

Commands reference

`varlock init`

Starts an interactive onboarding process to help you get started. Will help create your .env.schema and install varlock as a dependency if necessary.

varlock init

`varlock load`

Loads and validates environment variables according to your .env files, and prints the results. Default prints a nicely formatted, colorized summary of the results, but can also print out machine-readable formats.

Useful for debugging locally, and in CI to print out a summary of env vars.

varlock load [options]

Options:

--format: Format of output [pretty|json|env|shell]
--show-all: Shows all items, not just failing ones, when validation is failing
--env: Set the default environment flag (e.g., --env production), only useful if not using @currentEnv in .env.schema
--path / -p: Path to a specific .env file or directory to use as the entry point (overrides varlock.loadPath in package.json). Can be specified multiple times to load from multiple paths — later paths take higher precedence.

Examples:

# Load and validate environment variables
varlock load

# Load and validate for a specific environment (when not using @currentEnv in .env.schema)
varlock load --env production

# Output validation results in JSON format
varlock load --format json

# Output as shell export statements (useful for direnv / eval)
eval "$(varlock load --format shell)"

# When validation is failing, will show all items, rather than just failing ones
varlock load --show-all

# Load from a specific .env file
varlock load --path .env.prod

# Load from a specific directory
varlock load --path ./config/

# Load from multiple directories (later paths take higher precedence)
varlock load -p ./envs -p ./overrides

`varlock run`

Executes a command in a child process, injecting your resolved and validated environment variables from your .env files. This is useful when a code-level integration is not possible.

varlock run -- <command>

Options:

--no-redact-stdout: Disable stdout/stderr redaction to preserve TTY detection for interactive tools
--no-inject-graph: Disable injection of __VARLOCK_ENV serialized config graph into the child process environment
--path / -p: Path to a specific .env file or directory to use as the entry point. Can be specified multiple times to load from multiple paths — later paths take higher precedence.

Examples:

varlock run -- node app.js      # Run a Node.js application
varlock run -- python script.py # Run a Python script

# Use a specific .env file as entry point
varlock run --path .env.prod -- node app.js

# Use a specific directory as entry point
varlock run --path ./config/ -- node app.js

# Use multiple directories as entry points
varlock run -p ./envs -p ./overrides -- node app.js

Because of the way that shell expansion works, you may need to use use sh -c to properly expand environment variables in your command after varlock has injected them.

varlock run -- echo $MY_VAR # ❌ will not work
varlock run -- sh -c 'echo $MY_VAR' # ✅ will work

By default, varlock run pipes stdout/stderr through a redaction filter. To preserve color output, varlock automatically injects FORCE_COLOR into the child process environment when the parent terminal is a TTY. This means most CLI tools that use color libraries (chalk, kleur, etc.) will still display colors while redaction remains active.

For tools that require a fully connected TTY (e.g., interactive tools like psql or claude that use raw terminal features), use --no-redact-stdout to bypass piping entirely:

varlock run --no-redact-stdout -- claude --env development
varlock run --no-redact-stdout -- bash -c 'psql $DATABASE_URL'

Note: --no-redact-stdout disables stdout/stderr redaction entirely. Use it only when a tool needs true TTY pass-through.

By default, varlock run injects a __VARLOCK_ENV variable containing the full serialized config graph (including resolved sensitive values) into the child process environment. This is used by framework integrations to obtain sensitivity metadata without re-invoking the CLI.

For long-lived processes, interactive shells, or any workflow where subprocesses may inspect their environment (e.g., env, printenv, or an LLM-driven agent), use --no-inject-graph to omit this variable:

varlock run --no-inject-graph -- bash
varlock run --no-inject-graph -- claude

Note: When --no-inject-graph is set, framework integrations that rely on __VARLOCK_ENV will need to fall back to re-invoking the CLI. __VARLOCK_RUN=1 is always set regardless of this flag.

`varlock printenv`

Resolves and prints the value of a single environment variable to stdout. Only the requested item and its transitive dependencies are resolved, making this faster than loading the full graph.

This is useful within larger shell commands where you need to embed a single resolved env var value.

varlock printenv <VAR_NAME> [options]

Options:

--path / -p: Path to a specific .env file or directory to use as the entry point. Can be specified multiple times to load from multiple paths — later paths take higher precedence.

Examples:

# Print the resolved value of MY_VAR
varlock printenv MY_VAR

# Use a specific .env file as entry point
varlock printenv --path .env.prod MY_VAR

# Use multiple directories as entry points
varlock printenv -p ./envs -p ./overrides MY_VAR

# Embed in a shell command using subshell expansion
sh -c 'some-tool --token $(varlock printenv MY_TOKEN)'

Why not use varlock run -- echo $MY_VAR?

Shell expansion happens before varlock runs, so $MY_VAR is substituted by the shell with whatever value it already has (likely empty). varlock printenv avoids this by printing the value directly to stdout, letting you capture it with $(...) after varlock has resolved it.

varlock run -- echo $MY_VAR         # ❌ shell expands $MY_VAR before varlock runs
varlock printenv MY_VAR             # ✅ varlock resolves and prints the value
sh -c 'echo $(varlock printenv MY_VAR)'  # ✅ embed in a larger command

`varlock scan`

Scans your project files for sensitive config values that should not appear in plaintext. Loads your varlock config, resolves all @sensitive values, then checks files for any occurrences of those values.

This is especially useful as a pre-commit git hook to prevent accidentally committing secrets into version control.

varlock scan [options]

Options:

--staged: Only scan staged git files
--include-ignored: Include git-ignored files in the scan (by default, gitignored files are skipped)
--install-hook: Set up varlock scan as a git pre-commit hook
--path / -p: Path to a specific .env file or directory to use as the schema entry point. Can be specified multiple times to load from multiple paths — later paths take higher precedence.

Examples:

# Scan all non-gitignored files in the current directory
varlock scan

# Only scan staged git files
varlock scan --staged

# Scan all files, including gitignored ones
varlock scan --include-ignored

# Use a specific .env file as the schema entry point
varlock scan --path .env.prod

# Use multiple schema entry points
varlock scan -p ./envs -p ./overrides

# Set up as a git pre-commit hook
varlock scan --install-hook

The easiest way to set up scanning as a pre-commit hook is to run:

varlock scan --install-hook

This will detect if you are using a hook manager (like husky or lefthook) and provide the appropriate setup instructions. Otherwise, it will create a .git/hooks/pre-commit hook for you automatically.

If varlock is installed as a project dependency, the hook command will be automatically prefixed with your package manager (e.g., npx varlock scan).

You can also set it up manually — see the Secrets guide for more details.

`varlock typegen`

Generates type files according to @generateTypes and your config schema. Uses only non-environment-specific schema info, so output is deterministic regardless of which environment is active.

This command is particularly useful when you have set auto=false on the @generateTypes decorator to disable automatic type generation during varlock load or varlock run.

varlock typegen [options]

Options:

--path / -p: Path to a specific .env file or directory to use as the entry point. Can be specified multiple times to load from multiple paths — later paths take higher precedence.

Examples:

# Generate types using the default schema
varlock typegen

# Generate types from a specific .env file
varlock typegen --path .env.prod

# Generate types from multiple directories
varlock typegen -p ./envs -p ./overrides

`varlock telemetry`

Opts in/out of anonymous usage analytics. This command creates/updates a configuration file at $XDG_CONFIG_HOME/varlock/config.json (defaults to ~/.config/varlock/config.json) saving your preference.

varlock telemetry disable
varlock telemetry enable

`varlock help`

Displays general help information, alias for varlock --help

varlock help

For help about specific commands, use:

varlock subcommand --help

CLI Commands

Running commands in JS projects

package.json configuration

Commands reference

varlock init

varlock load

varlock run

varlock printenv

varlock scan

varlock typegen

varlock telemetry

varlock help

`package.json` configuration

`varlock init`

`varlock load`

`varlock run`

`varlock printenv`

`varlock scan`

`varlock typegen`

`varlock telemetry`

`varlock help`