Setup & Auth

vars init

npx dotvars init

Sets up a new vars project. vars:

1. Creates config.vars — single encrypted secrets file (safe to commit)
2. Creates .vars/key — master encryption key (gitignored)
3. Updates .gitignore — key and swap files excluded
4. Adds #vars import to package.json scripts

If a .env file exists, vars offers to import it. It reads the key-value pairs, guesses Zod schemas from the values, and encrypts everything before writing.

If config.vars already exists but .vars/key is missing (e.g., a fresh clone), running init again detects the incomplete setup and creates the missing key file.

Flags

Example

# Import from a non-default path, label values as "staging"
npx dotvars init --file .env.staging --env staging

vars key

Subcommands for managing your encryption key.

vars key init

npx dotvars key init

Generates a new .vars/key file. Run this on a fresh clone that already has a config.vars committed.

vars key fingerprint

npx dotvars key fingerprint

Prints a short fingerprint of the current key. Use it to verify that two machines share the same key without exposing the key itself.

vars key export

npx dotvars key export

Prints the raw key to stdout. Pipe it to a secure channel when sharing with a teammate or storing in CI.

# Copy key to clipboard (macOS)
npx dotvars key export | pbcopy

vars doctor

npx dotvars doctor

Runs health checks and prints a summary. Exits 1 if any check fails.

Checks

Files:

• config.vars exists
• .vars/key exists
• Codegen is up to date (generated file matches current schemas)

Security:

• .vars/key is gitignored
• Pre-commit hook installed
• All values are encrypted

Secrets Health:

• No expiring or deprecated secrets (warns if @expires is within 30 days, or past due)

Example output

◆  Files
│  ✓ config.vars found
│  ✓ .vars/key found
│  △ codegen up to date
│      Run vars gen to regenerate

◆  Security
│  ✓ .vars/key is gitignored
│  △ Pre-commit hook installed
│      Run vars hook to install

◆  Secrets Health
│  ✓ No expiring or deprecated secrets

Run it in CI to catch drift before it bites you in prod.

vars hook

npx dotvars hook

Installs a pre-commit hook that blocks commits when any *.unlocked.vars file is staged. This prevents accidentally committing decrypted secrets.

Run it once after cloning — vars init does this automatically for new projects.

vars completions

npx dotvars completions <shell>

Writes a shell completion script to stdout. Redirect it to wherever your shell loads completions from.

Supported shells

Open a new shell after running and tab-completion works for all vars subcommands.