CLI & CI/CD Integration

Overview

The CLI gives every developer and pipeline a first-class way to consume secrets securely. Instead of copy-pasting environment variables into CI settings or committing .env files, you run dotenvar pull and get a freshly decrypted .env file every time.

Installation

Via npm

npm install -g @dotenvar/cli

Via Homebrew (macOS)

brew install dotenvar

Via Chocolatey (Windows)

choco install dotenvar

Standalone binary

Pre-built binaries for macOS (ARM & x64), Linux (ARM & x64), and Windows are available on the GitHub Releases page. Useful for non-Node environments or Docker multi-stage builds.

Verify the install:

dotenvar --version

Authentication

Authentication is done once per machine using your existing Google account.

dotenvar auth login

dotenvar auth status   # show currently logged-in user
dotenvar auth logout   # revoke session

Project Setup

Run dotenvar init once inside each project that needs to pull secrets. This generates a deploy key for the project, re-seals your secrets for that key, and stores everything locally.

cd my-project
dotenvar init

The interactive wizard will ask for your Env ID (copy it from the group in the web app) and optionally your passphrase if one is set on your account. Everything after that is automatic:

? Enter your Env ID (copy from app.dotenvar.com): grp_abc123
? Passphrase: ••••••••

✓ Deploy key created and sealed
✓ Created dotenvar.json
✓ Created dotenvar.key
✓ dotenvar.key added to .gitignore
✓ .env added to .gitignore

  Ready. Run: dotenvar pull

Adding a second environment

To add another env (e.g. staging vs production) to the same project, run init with the --env flag. It appends a new line to dotenvar.key without touching the rest.

dotenvar init --env grp_def456

Pulling Secrets

After init, pull your secrets at any time. dotenvar reads dotenvar.json, resolves each env ID against dotenvar.key, decrypts locally, and writes a .env file.

dotenvar pull               # pull all envs in dotenvar.json
dotenvar pull --env grp_abc # pull one specific env
dotenvar pull --out .env.local  # override output path (single env only)

✓ 12 secrets written to .env

Running Commands with Secrets Injected

dotenvar exec injects secrets as environment variables into any child process without writing a .env file to disk. Ideal for production deployments or environments where you want zero plaintext on disk.

dotenvar exec -- node server.js
dotenvar exec -- python app.py
dotenvar exec -- go run main.go
dotenvar exec -- php artisan serve
dotenvar exec --env grp_abc -- npm run start

The process receives exactly the same environment variables as if you had sourced a .env file.

Deploy Keys

A deploy key is a scoped machine credential tied to a single environment. It is generated during dotenvar init and stored in dotenvar.key as a single base64 blob. Store it as a CI secret and the CLI handles the rest.

Print a deploy key for CI

Copy the blob for a specific env and store it as a CI environment secret (e.g. DOTENVAR_DEPLOY_KEY).

dotenvar deploy-key print --env grp_abc123
# DOTENVAR_DEPLOY_KEY=eyJ0b2tlbiI6ImRsa194eHh4IiwicHJpdmF0ZV9rZXkiOiItLS0tLUJFR0lO...
# ↑ paste this value into your CI secrets panel

Rotate a deploy key

Re-generates and re-seals the key without touching any other env.

dotenvar deploy-key rotate --env grp_abc123

Revoke a deploy key

Deletes the key on the server and removes the local entry. Any pipeline using that key will immediately stop working.

dotenvar deploy-key revoke --env grp_abc123

CI/CD Integration

Generate a deploy key with dotenvar deploy-key print --env <id>, store the blob as a CI secret named DOTENVAR_DEPLOY_KEY, then call dotenvar pull in your pipeline. That's it.

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DOTENVAR_DEPLOY_KEY: ${{ secrets.DOTENVAR_DEPLOY_KEY }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dotenvar CLI
        run: npm install -g @dotenvar/cli

      - name: Pull secrets
        run: dotenvar pull

      - name: Build
        run: npm run build

GitLab CI

deploy:
  variables:
    DOTENVAR_DEPLOY_KEY: $DOTENVAR_DEPLOY_KEY   # set in project CI/CD settings
  before_script:
    - npm install -g @dotenvar/cli
    - dotenvar pull
  script:
    - npm run build

Docker

Pass DOTENVAR_DEPLOY_KEY to the container at runtime via the -e flag. dotenvar exec reads it, fetches and decrypts your secrets from the server, injects them into the child process, and starts your app — nothing is written to disk.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci && npm install -g @dotenvar/cli
COPY . .
RUN npm run build

# DOTENVAR_DEPLOY_KEY is passed at container run time (see below)
CMD ["dotenvar", "exec", "--", "node", "dist/server.js"]

# Pass your deploy key at run time — this is the only secret the container needs
docker run \
  -e DOTENVAR_DEPLOY_KEY="eyJ0b2tlbiI6ImRsa194eHh4..." \
  -p 3000:3000 \
  my-app

Vercel / Netlify

Set DOTENVAR_DEPLOY_KEY in your project's environment variables panel, then use a custom build command:

# Vercel build command
dotenvar pull && next build

# Netlify build command
dotenvar pull && npm run build

Platform Guides

Step-by-step instructions for every CI/CD platform, deployment target, and language or framework. Select your platform to see the exact commands, config files, and where to store your deploy key.

dotenvar deploy-key print --env grp_abc123
# Outputs one line — copy the full value including "eyJ..."

name: Deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DOTENVAR_DEPLOY_KEY: ${{ secrets.DOTENVAR_DEPLOY_KEY }}
    steps:
      - uses: actions/checkout@v4

      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dotenvar CLI
        run: npm install -g @dotenvar/cli

      # Option A — write secrets to .env for subsequent build steps
      - name: Pull secrets
        run: dotenvar pull

      - name: Build
        run: npm run build

      # Option B — inject secrets into a specific process (no file written)
      - name: Run tests with secrets
        run: dotenvar exec -- npm test

Config Files

dotenvar.json - safe to commit

This file maps environment IDs to output paths. It contains no credentials and is safe to commit to version control.

{ "envId": "grp_abc123", "out": ".env" }

{
  "envs": [
    { "envId": "grp_abc123", "out": ".env" },
    { "envId": "grp_def456", "out": ".env.staging" }
  ]
}

dotenvar.key - never commit

This file stores one deploy key blob per environment ID. It is automatically added to .gitignore by dotenvar init. Each line is an env ID mapped to its base64-encoded deploy key blob.

grp_abc123=eyJ0b2tlbiI6ImRsa194eHh4IiwicHJpdmF0ZV9rZXkiOiItLS0tLUJFR0lO...
grp_def456=eyJ0b2tlbiI6ImRsaxyz...

Command Reference