project.mdx

title	Project commands
description	CLI reference for init, scan, install-plugin, flatten, telemetry, and help

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

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 [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

:::tip Install the Varlock agent skill with npx skills add dmno-dev/varlock or gh skill install dmno-dev/varlock varlock. See the AI Tools guide for more. :::

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, 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

:::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 install-plugin ||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 ||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 oauth ||oauth||

Manages OAuth providers defined with @oauthProvider and the refresh tokens used by oauth() items.

varlock oauth [status|login] [provider-id]

varlock oauth login

Runs a browser login flow against a provider and stores the resulting refresh token in the encrypted cache. Items using oauth(<id>, ...) without an explicit refreshToken resolve using this stored token from then on. Requires a persistent (disk) cache.

The requested scopes default to the union of scopes used by items referencing the provider, plus any provider-level scopes and preset-required scopes (e.g. offline_access for Microsoft).

Positional arguments:

• [provider-id]: which @oauthProvider to log in to (optional when only one is defined)

Flags:

• --flow <device|browser>: device shows a short code to enter on the provider's site (default when supported); browser opens the provider's consent page and catches the redirect on a local loopback server. The browser flow requires the OAuth app to allow loopback redirects (register it as a native/desktop app type).
• --scopes <string>: override the requested scopes
• --path / -p: env file entry point, same as other commands

Examples:

# log in (single provider defined)
varlock oauth login

# specific provider, forcing the loopback browser flow
varlock oauth login google --flow browser

Login-provisioned tokens live in this machine's encrypted cache: clearing the cache means logging in again. For CI, store a refresh token in your vault and pass it to oauth() via refreshToken instead.

varlock oauth status

Shows each defined provider, which items use it, and whether a refresh token has been provisioned. Bare varlock oauth does the same.

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