cli-commands.mdx

title	CLI Commands
description	Reference documentation for Varlock CLI commands

import ExecCommandWidget from "@/components/ExecCommandWidget.astro";

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:

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 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. 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` ||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` ||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)

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/

:::caution Setting @currentEnv in your .env.schema will override the --env flag. :::

### `varlock run` ||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
• --path / -p: Path to a specific .env file or directory to use as the entry point

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

:::note[Shell expansion of env vars in commands] 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

:::

:::note[Interactive tools and TTY detection] By default, varlock run pipes stdout/stderr through a redaction filter, which causes child processes to detect !process.stdout.isTTY and enter non-interactive mode. This can break interactive tools like claude or psql that require TTY detection.

Use --no-redact-stdout to disable stdout/stderr redaction and preserve TTY detection:

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

Note: This flag only disables stdout/stderr redaction. Other redaction mechanisms (like console patching) may still apply if enabled in your configuration. :::

### `varlock printenv` ||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

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

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

:::note[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` ||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

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

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

:::tip[Git pre-commit 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 audit` ||audit||

Scans your source code for environment variable references and compares them against keys defined in your schema.

This command reports two drift categories:

• Missing in schema: key is used in code but not declared in schema
• Unused in schema: key is declared in schema but not referenced in code

Exit codes:

• 0 when schema and code are in sync
• 1 when drift is detected

varlock audit [options]

Options:

• --path / -p: Path to a specific .env file or directory to use as the schema entry point

Examples:

# Audit current project
varlock audit

# Audit using a specific .env file as schema entry point
varlock audit --path .env.prod

# Audit using a directory as schema entry point
varlock audit --path ./config

:::note When --path points to a directory, code scanning is scoped to that directory tree. When it points to a file, scanning is scoped to that file's parent directory. :::

### `varlock typegen` ||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

Examples:

# Generate types using the default schema
varlock typegen

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

### `varlock telemetry` ||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

:::note You can also temporarily opt out by setting the VARLOCK_TELEMETRY_DISABLED environment variable. See the Telemetry guide for more information about our analytics and privacy practices. :::

### `varlock help` ||help||

Displays general help information, alias for varlock --help

varlock help

For help about specific commands, use:

varlock subcommand --help