Managing Variables

show, edit, hide. That's it. add, remove, ls, and toggle exist for when you'd rather not open the file at all.

show

npx dotvars show [file]

Decrypts a config.vars file and renames it to config.unlocked.vars. The encrypted values are replaced with their plaintext. Edit the file directly, then run hide.

Before it decrypts, vars auto-fixes safety issues:

• Warns if .vars/key is missing
• Warns if the pre-commit hook isn't installed

Flags

npx dotvars show -f staging.vars

hide

npx dotvars hide

Encrypts ALL unlocked .unlocked.vars files. Scans for any *.unlocked.vars file in the current project and encrypts each one, renaming it back to .vars. You don't need to specify a file.

Encryption is all-or-nothing per file — if any value fails, that file stays untouched. No partial writes, no corrupted state.

If schemas changed since the last gen run, hide regenerates the TypeScript types automatically.

Flags

npx dotvars hide -f staging.vars

toggle

npx dotvars toggle [file]

Checks the current lock state of the file (by extension) and runs the right command. File is .unlocked.vars? Hides it. File is .vars? Shows it. Same command either way.

Flags

add

npx dotvars add NAME

Adds a variable without opening the file. vars prompts you for a Zod schema, then asks for a value per environment (default, dev, staging, prod). Skip any env you don't need yet.

The variable is encrypted and written straight into config.vars.

Names must be UPPER_SNAKE_CASE. Mark a variable as non-secret with the public keyword prefix — public variables are stored in plaintext and do not require a key to read.

Flags

npx dotvars add STRIPE_KEY --schema "z.string().startsWith('sk_')"

remove

npx dotvars remove NAME

Deletes the variable, every env value, and all metadata. Prompts for confirmation first.

Flags

npx dotvars remove OLD_API_URL --yes

ls

npx dotvars ls

Without a file argument: prints an overview of all *.vars files in the project with their lock state and variable count.

FILE              STATE     VARS
config.vars       locked    12
staging.vars      unlocked   5

With a file argument: prints a table of every variable in that file — schema, which envs have values, required vs optional, and any metadata (description, owner, expiry, deprecation). Deprecated vars show with strikethrough.

npx dotvars ls config.vars

NAME             SCHEMA                  ENVS                  STATUS
DATABASE_URL     z.string().url()        dev, staging, prod    required
PORT             z.coerce.number()       default               optional
~~OLD_API_URL~~  z.string().url()        default               deprecated

Flags

Day-to-day

# Unlock (config.vars → config.unlocked.vars)
npx dotvars show

# Edit config.unlocked.vars directly

# Lock (config.unlocked.vars → config.vars)
npx dotvars hide

Or skip the file entirely and use add and remove.