Installation

There are two ways to install Varlock:

1. Install as a package.json dependency in JavaScript/TypeScript projects (the varlock CLI package)
2. Install as a standalone binary

If you prefer to let your AI agent install Varlock for you, you can skip these instructions and build a prompt for your agent:

Open Prompt Builder

Docs MCP

There is also a Docs MCP server that exposes a search tool. See more details here.

As a JavaScript/TypeScript dependency

Requires:

• Node.js version 22 or higher

Installation

To install varlock in your project, run:

npm

npx varlock init

pnpm

pnpm dlx varlock init

bun

bunx varlock init

vlt

vlx varlock init

yarn

yarn dlx varlock init

This will install varlock as a dependency and scan your project for .env files and create a .env.schema file in the root of your project. Depending on your project configuration, it will optionally:

• Remove your existing .env.example file
• Add decorators to your .env.schema file to specify the type of each environment variable

For AI agent workflows, use non-interactive mode instead:

npm

npx varlock init --agent

pnpm

pnpm dlx varlock init --agent

bun

bunx varlock init --agent

vlt

vlx varlock init --agent

yarn

yarn dlx varlock init --agent

As a standalone binary

To install varlock CLI as a binary, run:

# Install via homebrew
brew install dmno-dev/tap/varlock

# OR via cURL
curl -sSfL https://varlock.dev/install.sh | sh -s

Then run the setup wizard to help you get started:

varlock init

Antivirus false positives

If Microsoft Defender or another scanner flags a varlock-local-encrypt binary on any platform, see the local encryption guide, antivirus false positives for verification and recovery steps.

Installation script usage

Usage: install.sh [options]

install varlock binary

Options:
  --dir             directory to install varlock to (defaults to $XDG_CONFIG_HOME/varlock/bin, else ~/.varlock/bin if it exists, else ~/.config/varlock/bin)
  --reinstall       reinstall even if already installed (default: false)
  --version         version of varlock to install (defaults to latest)
  --force-no-brew   force install without homebrew even when detected (default: false)
  --skip-win-exe    on WSL, skip installing the Windows encryption helper (varlock-local-encrypt.exe) (default: false)

Verifying a release

Both install paths already check integrity for you: the homebrew formula pins a sha256 per archive, and install.sh verifies the downloaded archive against the release’s checksums.txt before installing.

If you are pinning varlock yourself (a container image, a provisioning script, or a tool that installs varlock on a user’s behalf), download the archive from the release tag and verify it the same way:

VERSION=1.14.0
BASE="https://github.com/dmno-dev/varlock/releases/download/varlock@${VERSION}"
ARCHIVE="varlock-linux-x64.tar.gz"

curl -sSfLO "${BASE}/${ARCHIVE}"
curl -sSfLO "${BASE}/checksums.txt"

grep " ${ARCHIVE}\$" checksums.txt | sha256sum -c -
# on macOS, which has no sha256sum:
grep " ${ARCHIVE}\$" checksums.txt | shasum -a 256 -c -

checksums.txt is signed with cosign keyless signing, so you can also confirm it came from varlock’s release workflow rather than from someone with write access to the repo’s releases. The signature covers checksums.txt, which in turn covers every archive by hash:

curl -sSfLO "${BASE}/checksums.txt.cosign.bundle"

cosign verify-blob checksums.txt \
  --bundle checksums.txt.cosign.bundle \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/dmno-dev/varlock/\.github/workflows/(release|binary-release)\.yaml@refs/heads/main$'

Both workflow identities are accepted because binaries are normally cut by release.yaml alongside the npm publish, and re-cut by binary-release.yaml when an already-published version needs new archives.

Note

Signing was added after varlock 1.14.0, so older releases have checksums.txt but no bundle. If a release has no checksums.txt.cosign.bundle asset, it predates signing and only the checksum step applies.

Varlock skill

Then install the Varlock agent skill:

skills

npx skills add dmno-dev/varlock

GitHub CLI

Requires GitHub CLI v2.90+.

gh skill install dmno-dev/varlock varlock

See the AI Tools guide for update commands and agent-specific options.

Editor and shell tooling

Varlock ships with first-party tooling that makes authoring .env.schema files much easier. Set these up right after installing the CLI.

VS Code extension

Install the @env-spec VS Code extension from the VS Code Marketplace or Open VSX (for Cursor, Windsurf, and other VS Code forks).

It provides syntax highlighting, decorator and @type IntelliSense, $KEY reference completion, and inline validation while you edit .env.schema and other @env-spec files.

Shell completion

Enable tab completion for varlock commands and flags in bash, zsh, or fish. See the Shell completion guide for one-time setup. Usually, adding eval "$(varlock complete)" to your shell profile is enough.