Project commands

`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 [options]

Options:

--agent: Run non-interactively for agent/automation workflows. Skips confirmation prompts and uses deterministic defaults for schema generation.

Examples:

# Interactive setup wizard
varlock init

# Non-interactive setup for AI agents
varlock init --agent

`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, and for scanning build output to ensure no secrets leaked into files that will be published or deployed.

Exit codes: 0 when no plaintext secrets are found; 1 when a leaked value is detected. This makes it usable directly as a pre-commit hook or CI gate.

varlock scan [paths...] [options]

Positional arguments:

[paths...]: Optional list of file paths, directories, or glob patterns to scan. When provided, only these targets are scanned: git filtering (--staged, --include-ignored) is bypassed and build-output directories that are normally skipped (such as dist, .next, build) are included.

Options:

--staged: Only scan staged git files (ignored when explicit paths are provided)
--include-ignored: Include git-ignored files in the scan (ignored when explicit paths are provided)
--install-hook: Set up varlock scan as a git pre-commit hook
Common options: --path / -p (here it sets the schema entry point used to resolve sensitive values)

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

# Scan a specific build output directory (e.g. to check for leaked secrets before publishing)
varlock scan ./dist

# Scan multiple directories
varlock scan ./dist ./public

# Scan files matching a glob pattern
varlock scan './dist/**/*.js'

# 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 install-plugin`

Pre-downloads a plugin from npm into the local varlock plugin cache so it is available without an interactive confirmation prompt. This is mainly for the standalone binary in CI or other non-interactive environments. When varlock runs as a package.json dependency, plugins resolve through your normal node_modules instead.

The plugin must be specified with an exact version (name@version).

varlock install-plugin <name@version>

Positional arguments:

<name@version>: The plugin to install, with an exact version (e.g. my-plugin@1.2.3).

Examples:

# Install a plugin at an exact version
varlock install-plugin my-plugin@1.2.3

# Scoped package
varlock install-plugin @my-scope/my-plugin@2.0.0

`varlock flatten`

Copies every env file reachable via @import() into one self-contained directory and rewrites the @import paths. Use it when only part of a monorepo is available at runtime, most commonly the final stage of a Docker build. See the Docker guide for the full workflow.

By default, values are never resolved and plugins are never executed: this is a purely structural transform, safe to run in CI without secrets. (--vendor-plugins copies plugin code into the output, but still never resolves values.)

Details of the transform:

Files imported from outside the package are mirrored under .env-imports/ inside the output directory, preserving their workspace-relative paths, so relative imports between copied files keep working.
Imports that are conditionally disabled (via enabled=) are still copied, with the condition preserved, since a different environment may enable them at runtime.
.env.local and .env.[env].local files are skipped by default (use --include-local to include them).
@plugin() declarations in copied files get their versions pinned to whatever is currently installed, so varlock can auto-install them where the original package’s node_modules is not available. Plugins declared via a local path are copied into the output.
With --vendor-plugins, npm @plugin() packages are copied into .env-plugins/ (from your node_modules, downloading only any that are not installed) and the declarations are rewritten to local paths, so the output resolves with no runtime install. This is the way to run plugins in shell-less, offline, or distroless images. See plugins in containers.
Imports pointing outside the workspace root (including ~/ home-directory imports) are left untouched with a warning.

varlock flatten [options]

Options:

--out-dir <path>: Output directory, relative to the current directory (default .env-flat)
--include-local: Include .env.local / .env.*.local files (excluded by default)
--vendor-plugins: Copy npm plugins into the output so no runtime install is needed. Uses the copy in your node_modules, downloading only any that are not installed

Examples:

# Flatten env files from the current directory into .env-flat/
varlock flatten

# Custom output location
varlock flatten --out-dir dist/env

# Also vendor plugins for a self-contained, distroless-ready output
varlock flatten --vendor-plugins

The output directory is a generated artifact: add it to .gitignore, and rerun flatten whenever your env files change.

`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