New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details → →

Book a Demo Sign in

vaulter

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

vaulter

Multi-backend environment variable and secrets manager with AES-256-GCM encryption

latest

Source

npm

Version: 1.0.73

Version published: 5 hours ago

Maintainers: 1

Created: 3 months ago

Source

vaulter

Multi-Backend Environment & Secrets Manager

Organizes your .env files with structure and best practices.
Powered by dotenv for parsing. Store secrets anywhere: S3, MinIO, R2, or filesystem.

Installation

curl -fsSL https://raw.githubusercontent.com/forattini-dev/vaulter/main/install.sh | sh
# or: npm install -g vaulter

Quick Start

Minimal

vaulter init                                          # Initialize project
vaulter key generate --name master                    # Generate encryption key
vaulter change set DATABASE_URL="postgres://..." -e dev  # Set secret
vaulter change set PORT::3000 -e dev                     # Set config (plain)
vaulter change set NODE_ENV=local -e dev                 # Set config (sensitive=false)
vaulter change move API_KEY --from shared --to api -e dev # Move variable to service
vaulter change move API_KEY --from shared -e dev -s svc-notifications   # Infer destination service
vaulter plan -e dev                                      # Preview changes before applying
eval $(vaulter export shell -e dev)                   # Export to shell

End-to-End (Monorepo, `web` + `api`)

This flow shows local editing, team sharing, and promotion across multiple environments.

# 0) Initialize + discover services
vaulter init --monorepo
vaulter key generate --name master
vaulter services

# 1) Create/override vars locally (offline by default)
# `local set` writes only to `.vaulter/local/*`; use `-e/--env` only for backend-aware operations.
vaulter local set NEXT_PUBLIC_APP_NAME=Portal        --shared
vaulter local set NODE_ENV=local                    --shared
vaulter local set DATABASE_URL=postgres://...        -s api
vaulter local set REDIS_URL=redis://...             -s api
vaulter local set QUEUE_ENABLED::true               -s api
vaulter local set WORKER_CONCURRENCY::4             -s web
vaulter local pull --all                             # Generates .env for local run (all outputs)
vaulter local diff                                # Review local overrides

# 2) Share source of truth with team (backend sync)
vaulter local push --all -e dev

# 3) Team members pull and generate local envs
vaulter local sync -e dev
vaulter local pull --all

# 4) Promote the same managed set to multiple environments
for ENV in dev stg prd; do
  echo "Deploying to $ENV"
  vaulter plan -e "$ENV"
  vaulter apply -e "$ENV" $( [ "$ENV" = "prd" ] && echo '--force' )
done

# 5) Run your scripts with vaulter-managed variables
vaulter run -e dev -- pnpm start                  # Local run with local overrides
vaulter run -e dev -s web -- pnpm --dir apps/web dev
vaulter run -e dev -s api -- pnpm --dir apps/api lint
vaulter run -e stg -s api -- pnpm --dir apps/api migrate
vaulter run -e prd -- docker compose -f ./deploy/docker/docker-compose.yml up

# 6) Export service-specific artifacts per environment
# Config-like outputs
vaulter export env -e dev --service api > apps/api/.env
vaulter export env -e stg --service web > apps/web/.env
vaulter export shell -e prd --service api > /tmp/api-env.sh

# Kubernetes artifacts
vaulter export k8s-secret -e dev --service api --name api-secrets
vaulter export k8s-secret -e dev --service web --name web-secrets
vaulter export k8s-secret -e stg --service api --name api-secrets
vaulter export k8s-secret -e prd --service api --name api-secrets

# Deployment formats
vaulter export k8s-configmap -e prd --service api --name api-configmap
vaulter export helm -e prd --service api --name api-values

--force is required on apply -e prd and other production-like environments.

🔄 Development Workflow

Vaulter follows a backend-sync workflow where the backend is the source of truth and local overrides are for personal customization.

The Golden Rule

Backend is the source of truth. Everything syncs via backend.

Component	Git Status	Purpose
`.vaulter/config.yaml`	✅ Committed	Project configuration
*`.vaulter/local/`**	❌ Gitignored	Personal local overrides
*`.env` files**	❌ Gitignored	Generated outputs

Directory Structure

.vaulter/
├── config.yaml              # ✅ Committed - Project config
├── local/                   # ❌ Gitignored - Personal overrides
│   ├── configs.env          # Non-sensitive overrides (DEBUG, PORT)
│   ├── secrets.env          # Sensitive overrides (test API keys)
│   └── services/            # Monorepo per-service overrides
│       └── api/
│           ├── configs.env
│           └── secrets.env
└── dev/                     # ❌ Gitignored - Environment data (--dir mode)
    ├── configs.env          # Shared non-sensitive vars
    ├── secrets.env          # Shared sensitive vars
    └── services/            # Monorepo service vars
        └── api/
            ├── configs.env
            └── secrets.env

apps/web/.env                # ❌ Gitignored - Generated output
apps/api/.env                # ❌ Gitignored - Generated output

Directory modes:

.vaulter/local/ - Personal overrides (never synced to backend)
.vaulter/{env}/ - Environment data (synced with --dir mode)

.gitignore Setup

# Vaulter - only commit config.yaml
.vaulter/local/
*.env
.env.*

Daily Workflow

# 1. Start: Pull latest from backend + apply your local overrides
vaulter local pull

# 2. Work: Add personal overrides (not shared with team)
vaulter local set DEBUG::true                  # Shared override
vaulter local set PORT::3001                   # Service-specific (inferred from cwd in monorepo)

# 3. Add new variable for team? Push to backend
vaulter local set NEW_VAR=value --shared        # Personal scratch pad
vaulter local push                             # Share scratch locally with team
vaulter plan -e dev                            # Preview changes (recommended)
vaulter apply -e dev                           # Apply after approval

# 4. Check: See what's different
vaulter diff -e dev                             # Local vs backend diff

# 5. Promote: Clone to staging/production
vaulter clone dev stg --dry-run                # Preview
vaulter clone dev stg                          # Execute

Environment Promotion Flow

┌─────────────────────────────────────────────────────────────────┐
│                     DEVELOPMENT WORKFLOW                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   LOCAL (.vaulter/local/)      ◄── Personal only (gitignored)   │
│   ├── configs.env                                               │
│   └── secrets.env                                               │
│          │                                                       │
│          │ merged on `vaulter local pull`                       │
│          ▼                                                       │
│                                                                  │
│   BACKEND (S3/MinIO)           ◄── Source of truth (synced)     │
│   ├── dev/  ──────────────────────────────────────────────┐     │
│   │   └── all vars (encrypted)                            │     │
│   │                                                       │     │
│   ├── stg/  ◄─────── vaulter clone dev stg ──────────────┤     │
│   │   └── all vars (encrypted)                            │     │
│   │                                                       │     │
│   └── prd/  ◄─────── vaulter clone stg prd ──────────────┘     │
│       └── all vars (encrypted)                                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Team Collaboration

Team collaboration assumes one shared truth for each environment (backend) and private, local overrides per developer.

New team member setup (2 minutes):

git clone <repo>                    # Gets .vaulter/config.yaml
export VAULTER_KEY_DEV=<from-team>  # Get key securely from team
vaulter local sync -e dev           # Pull remote vars to .vaulter/local/
vaulter local pull --all            # Generate .env files (offline)

Why this is stable for teams

vaulter local set is always a private, working-copy edit. It does not change what others consume by itself.
vaulter local push is how you publish team-visible changes from local overrides.
vaulter local sync is how others consume published changes.
Use environment-specific gates (status, diff, and plan/apply) before merging critical updates.

Recommended sharing flow (single variable):

# 1) Add locally first
vaulter local set --shared NEW_FEATURE::enabled  # Shared config
vaulter local diff                                 # Verify local change before publishing

# 2) Optional dry-run share preview
vaulter local push --shared --dry-run -e dev         # Checks what would be pushed

# 3) Share to backend (explicit approval step before running)
vaulter local push --shared -e dev

# 4) Notify team
# "New var published. Run: vaulter local sync -e dev && vaulter local pull --all"

Monorepo service rule (recommended):

Defaults are shared only when genuinely global.
Service behavior should live in service scope (-s svc-*) unless explicitly cross-service.
Keep service ownership rules documented in .vaulter/config.yaml (policy), so mistakes are prevented early.

Conflict resolution if two devs edit same key

vaulter local diff -s <service>          # See your local delta
vaulter local sync -e dev                # Pull latest from backend
vaulter local pull --all                  # Rebuild outputs
vaulter local diff -s <service>          # Re-check before pushing

If divergence remains:

Ask one owner to pause and re-publish.
Prefer vaulter plan -e dev + manual review for sensitive or cross-service keys.

Important: Most local commands are local-only. Passing -e/--env is only needed when publishing or syncing with backend.

MCP Tools for Workflow

Task	Tool
Check health	`vaulter_status action="scorecard"`
Pull with overrides	`vaulter_local action="pull"`
Set shared override	`vaulter_local action="shared-set" key="DEBUG" value="true"`
Set service override	`vaulter_local action="set" key="PORT" value="3001"`
See differences	`vaulter_diff`
Compare environments	`vaulter_search source="dev" target="prd"`

What is Vaulter?

Vaulter is an opinionated organizer for your environment variables. It uses dotenv under the hood for parsing .env files - we don't reinvent the wheel, we just add structure.

# Install in your project
pnpm add vaulter
# or: npm install vaulter

What vaulter adds on top of dotenv:

Feature	dotenv	vaulter
Parse `.env` files	✅	✅ (uses dotenv)
Organize by environment (dev/stg/prd)	❌	✅
Separate local vs deploy files	❌	✅
Auto-detect environment (local/CI/K8s)	❌	✅
Encrypted remote storage	❌	✅
Sync between team members	❌	✅
Export to K8s, Helm, Terraform	❌	✅

Philosophy: Your local .env stays local (gitignored). Configs are committed. Secrets are encrypted in your own storage.

Quick Start (Local Development)

// app.ts
import { config } from 'vaulter'

config() // Loads from .vaulter/local/ (configs.env + secrets.env)

# Run commands with env vars loaded
npx vaulter run -- pnpm dev

# Or pull from backend first
vaulter local pull

That's it! For most local development, vaulter is just a structured dotenv.

🩺 Health Check - Status

Always start with vaulter status to diagnose your setup:

vaulter status -e dev
vaulter status -e dev --offline

Status performs up to 18 checks online, or a local-first subset in --offline.

Check	What It Does
✅ Connection	Tests backend connectivity (skipped in `--offline`)
✅ Latency	Measures operation speed
✅ Permissions	Validates read/write/delete access
✅ Encryption	Tests encrypt → decrypt round-trip
✅ Sync Status	Compares local vs remote
✅ Security	Detects .env in git, weak keys
✅ Scope Policy	Checks `shared` vs `service` assignment rules
✅ Perf Config	Suggests cache/warmup/concurrency tuning
✅ +8 more	Config, project, environment, backend, keys, etc.

Example output:

✓ ok: 15 | ⚠ warn: 1 | ✗ fail: 1

✓ connection: connected (24 vars in dev)
✓ latency: read=45ms, list=67ms
✓ permissions: read/write/delete OK
✓ encryption: round-trip successful
⚠ sync-status: 5 local-only, 3 remote-only, 2 conflicts
✗ security: 2 .env files tracked in git
  → Add to .gitignore immediately

When to use:

🆕 Initial setup - validate configuration
🐛 Debugging - identify root cause
🚀 Pre-deploy - ensure everything is synced
🔄 Routine - weekly health check

Runbook local (`scripts/vaulter-verify-dev.sh`)

For a quick pre-deploy validation in local/dev workflows:

VAULTER_VERIFY_ENV=dev pnpm run verify:vaulter
VAULTER_VERIFY_OFFLINE=0 VAULTER_VERIFY_REQUIRE_CONFIG=1 pnpm run verify:vaulter

The script runs:

vaulter status -e <env> -v [--offline] (offline by default)
vaulter diff -e <env> --values
vaulter list -e <env>

It writes an execution log under artifacts/vaulter-health/ for auditability.

For AI Agents: Call vaulter_status action="scorecard" once at the start of a new session (or when operations fail / environments change) to understand the current state before performing sensitive operations.

See docs/DOCTOR.md for complete guide.

Commands

Setup

Command	Description
`init`	Initialize project config
`init --split`	Initialize with split mode (configs/secrets dirs)

Health

Command	Description
`status -e <env>`	Full diagnostic report with checks and suggestions

Mutations (`change`)

Command	Description
`change set KEY=val -e <env>`	Set secret (encrypted)
`change set KEY::val -e <env>`	Set config (plain text)
`change set KEY:=123 -e <env>`	Set typed secret (number/boolean)
`change delete <key> -e <env>`	Delete variable
`change move <key> --from <scope> --to <scope> -e <env>`	Move/copy variable between scopes
`change import -f <file> -e <env>`	Import variables from file
`list -e <env>`	List all variables

Set syntax: = encrypted secret · :: plain config · := typed secret

In monorepo mode, when --service is resolved, one of --from or --to can be omitted and inferred from the active service.

Plan & Apply

Command	Description
`plan -e <env>`	Compute diff local vs backend, generate plan artifact
`apply -e <env>`	Execute plan, push changes to backend
`diff -e <env>`	Quick diff without plan artifacts
`plan --dir -e <env>`	Plan from `.vaulter/{env}/` directory
`plan [--plan-output <file>] -e <env>`	Write plan artifact (`.json` + `.md`). If `--plan-output` is omitted, defaults to `artifacts/vaulter-plans/<project>-<env>-<timestamp>.*`

Recommended daily path

vaulter local pull → vaulter local set → vaulter local push (when ready)
vaulter change set → vaulter change move → vaulter plan -e <env> → vaulter apply -e <env>
vaulter plan -e <env> → validate → vaulter apply -e <env>
vaulter status -e <env> for quick pre-flight health check

Export

Command	Description
`export shell -e <env>`	Export for shell `eval $(...)`
`export k8s-secret -e <env>`	Generate Kubernetes Secret (sensitive vars only)
`export k8s-configmap -e <env>`	Generate Kubernetes ConfigMap (config vars only)
`export helm -e <env>`	Generate Helm values.yaml
`export terraform -e <env>`	Generate Terraform .tfvars
`export docker -e <env>`	Docker env-file format
`export vercel -e <env>`	Vercel environment JSON
`export github-actions -e <env>`	GitHub Actions secrets

Services (monorepo)

Command	Description
`services list`	List discovered services
`services`	Same as `services list`

Audit & Rotation

Command	Description
`audit list -e <env>`	List audit entries
`audit stats -e <env>`	Show statistics
`rotation list -e <env>`	Check rotation status
`rotation run -e <env>`	CI/CD gate for overdue secrets

Key Management

Command	Description
`key generate --name <n>`	Generate symmetric key
`key generate --env <env>`	Generate key for specific environment
`key generate --name <n> --asymmetric`	Generate RSA/EC key pair
`key list`	List all keys
`key export --name <n>`	Export encrypted bundle
`key import -f <file>`	Import encrypted bundle
`key backup -o <file>`	Backup keys to encrypted bundle
`key restore -f <file>`	Restore keys from backup bundle

Run (Execute with Env Vars)

Command	Description
`run -- <command>`	Execute command with auto-loaded env vars
`run -e prd -- <command>`	Execute with specific environment
`run -s api -- <command>`	Execute with service-specific vars (monorepo)
`run --verbose -- <command>`	Show which files were loaded
`run --dry-run -- <command>`	Preview without executing

Examples:

# Local development
npx vaulter run -- pnpm dev

# CI/CD build with production vars
npx vaulter run -e prd -- pnpm build

# Monorepo service
npx vaulter run -e dev -s api -- pnpm start

Run scripts via package.json

Use vaulter run directly in your npm scripts to keep variables centralized and explicit.

{
  "scripts": {
    "dev:web": "vaulter run -e dev -s web -- pnpm --dir apps/web dev",
    "lint:api": "vaulter run -e dev -s api -- pnpm --dir apps/api lint",
    "migrate:api:stg": "vaulter run -e stg -s api -- pnpm --dir apps/api run migrate",
    "deploy:api:prd": "vaulter run -e prd -s api -- pnpm --dir apps/api build && vaulter export k8s-secret -e prd -s api --name api-secrets"
  }
}

npm run dev:web
npm run lint:api
npm run migrate:api:stg

The important part is that vaulter run stays as the first command so variable resolution and scope resolution happen before your script command.

The run command auto-detects the environment (local, CI, K8s) and loads the appropriate files before executing your command.

Run vaulter --help or vaulter <command> --help for all options.

Security

Every secret is encrypted before leaving your machine using AES-256-GCM.

Symmetric (Default)

vaulter key generate --name master

Asymmetric (RSA/EC)

For CI/CD separation: public key encrypts, private key decrypts.

vaulter key generate --name master --asymmetric              # RSA-4096
vaulter key generate --name master --asym --alg ec-p256      # EC P-256

# .vaulter/config.yaml
encryption:
  mode: asymmetric
  asymmetric:
    algorithm: rsa-4096
    key_name: master    # ~/.vaulter/projects/<project>/keys/master[.pub]

CI/CD: Give CI only the public key (can write, can't read). Production gets the private key.

Per-Environment Keys

Use different encryption keys for each environment (dev, stg, prd). This provides complete isolation - production secrets can't be decrypted with dev keys.

# Generate keys for each environment
vaulter key generate --env dev
vaulter key generate --env stg
vaulter key generate --env prd

Keys are stored in ~/.vaulter/projects/{project}/keys/{env}.

Key Resolution Order (per environment):

Priority	Source	Example
1	Env var `VAULTER_KEY_{ENV}`	`VAULTER_KEY_PRD=my-secret`
2	Config `encryption.keys.{env}`	See below
3	File `keys/{env}`	`~/.vaulter/projects/myapp/keys/prd`
4	Env var `VAULTER_KEY`	Global fallback
5	Config `encryption.key_source`	Default config
6	File `keys/master`	Default fallback

Per-environment config:

# .vaulter/config.yaml
encryption:
  keys:
    dev:
      source:
        - env: VAULTER_KEY_DEV
        - file: ~/.vaulter/projects/myapp/keys/dev
    prd:
      source:
        - env: VAULTER_KEY_PRD
      mode: asymmetric  # Optional: different mode per env

Multi-app isolation:

~/.vaulter/projects/
├── app-landing/keys/
│   ├── dev    # app-landing dev key
│   ├── stg    # app-landing stg key
│   └── prd    # app-landing prd key
├── app-api/keys/
│   ├── dev    # app-api dev key (DIFFERENT from app-landing)
│   └── prd
└── svc-auth/keys/
    └── prd

Each app has completely isolated secrets - app-landing/prd keys cannot decrypt app-api/prd secrets.

Shared Variables Key (Monorepo)

In monorepos, shared variables need a consistent encryption key. Use shared_key_environment to specify which environment's key encrypts shared vars:

# .vaulter/config.yaml
encryption:
  shared_key_environment: dev  # Use dev key for all shared vars
  keys:
    dev:
      source:
        - env: VAULTER_KEY_DEV
    prd:
      source:
        - env: VAULTER_KEY_PRD

Why this matters:

Shared vars (__shared__ service) need ONE key to encrypt/decrypt
Without shared_key_environment, vaulter uses the current environment's key
This can cause issues when different environments have different keys

Example flow:

# Set shared var (uses dev key because shared_key_environment: dev)
vaulter change set LOG_LEVEL=debug -e dev --scope shared

# Read shared var from prd (still uses dev key for shared vars)
vaulter list -e prd --shared  # Works! Uses dev key for shared

Configuration

# .vaulter/config.yaml
version: "1"
project: my-project

backend:
  url: s3://bucket/envs?region=us-east-1

encryption:
  key_source:
    - env: VAULTER_KEY
    - file: .vaulter/.key
  rotation:
    enabled: true
    interval_days: 90
    patterns: ["*_KEY", "*_SECRET", "*_TOKEN"]

environments: [dev, stg, prd]
default_environment: dev

audit:
  enabled: true
  retention_days: 90

scope_policy:
  mode: warn
  inherit_defaults: true
  rules:
    - name: api-keys-service
      pattern: '^API_'
      expected_scope: service
      expected_service: svc-app
      reason: 'API_* vars are service-owned'
    - name: app-url-shared-default
      pattern: '^APP_.*_URL$'
      expected_scope: shared
      reason: 'URL variables stay shared by default'

# Local development files (see "Local vs Deploy Structure" below)
# local: .vaulter/local/

# CI/CD deploy files (see "Local vs Deploy Structure" below)
# deploy: .vaulter/deploy/

Backend URLs

Provider	URL
AWS S3	`s3://bucket/path?region=us-east-1`
MinIO	`http://KEY:SECRET@localhost:9000/bucket`
Cloudflare R2	`https://KEY:SECRET@ACCOUNT.r2.cloudflarestorage.com/bucket`
DigitalOcean	`https://KEY:SECRET@nyc3.digitaloceanspaces.com/bucket`
FileSystem	`file:///path/to/storage`

Local vs Deploy Structure

Vaulter separates local development from deployment configurations:

.vaulter/
├── config.yaml
├── local/                     # Developer machine (gitignored)
│   ├── configs.env            # Non-sensitive (sensitive=false)
│   ├── secrets.env            # Sensitive (sensitive=true)
│   └── services/              # Monorepo only
│       └── <service>/
│           ├── configs.env
│           └── secrets.env
└── deploy/                    # CI/CD pipelines
    ├── configs/               # Committed to git
    │   ├── dev.env
    │   ├── stg.env
    │   └── prd.env
    └── secrets/               # Gitignored, pulled from backend
        ├── dev.env
        └── prd.env

Why this structure:

Location	Purpose	Git	Contains
`local/configs.env`	Developer's machine	Ignored	Non-sensitive local vars
`local/secrets.env`	Developer's machine	Ignored	Sensitive local secrets
`deploy/configs/*.env`	CI/CD configs	Committed	Non-sensitive (PORT, HOST, LOG_LEVEL)
`deploy/secrets/*.env`	CI/CD secrets	Ignored	Pulled via `vaulter local sync`

Gitignore:

# Local development
.vaulter/local/configs.env
.vaulter/local/secrets.env
.vaulter/local/services/

# Deploy secrets (pulled in CI)
.vaulter/deploy/secrets/

CI/CD

GitHub Action (Recommended)

Use the official Vaulter GitHub Action for seamless CI/CD integration:

- uses: forattini-dev/vaulter@v1
  id: secrets
  with:
    backend: s3://my-bucket/secrets
    project: my-app
    environment: prd
    outputs: env,k8s-secret
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

Output Formats

Output	File	Use Case
`env`	`.env`	Docker, Node.js
`json`	`vaulter-vars.json`	Custom scripts
`k8s-secret`	`k8s-secret.yaml`	`kubectl apply`
`k8s-configmap`	`k8s-configmap.yaml`	`kubectl apply`
`helm-values`	`helm-values.yaml`	`helmfile`, `helm`
`tfvars`	`terraform.auto.tfvars`	`terraform`, `terragrunt`
`shell`	`vaulter-env.sh`	`source` in scripts

Full Examples

kubectl:

- uses: forattini-dev/vaulter@v1
  with:
    backend: ${{ secrets.VAULTER_BACKEND }}
    project: my-app
    environment: prd
    outputs: k8s-secret,k8s-configmap
    k8s-namespace: my-namespace
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

- run: |
    kubectl apply -f k8s-secret.yaml
    kubectl apply -f k8s-configmap.yaml

Helmfile:

- uses: forattini-dev/vaulter@v1
  with:
    backend: ${{ secrets.VAULTER_BACKEND }}
    project: my-app
    environment: prd
    outputs: helm-values
    helm-values-path: ./helm/secrets.yaml
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

- run: helmfile -e prd apply

Terraform/Terragrunt:

- uses: forattini-dev/vaulter@v1
  with:
    backend: ${{ secrets.VAULTER_BACKEND }}
    project: infra
    environment: prd
    outputs: tfvars
    # .auto.tfvars is loaded automatically by Terraform!
    tfvars-path: ./secrets.auto.tfvars
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

- run: terragrunt apply -auto-approve

Docker Build:

- uses: forattini-dev/vaulter@v1
  with:
    backend: ${{ secrets.VAULTER_BACKEND }}
    project: my-app
    environment: prd
    outputs: env
    env-path: .env.production
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

- run: docker build --secret id=env,src=.env.production -t app .

Export to GITHUB_ENV:

- uses: forattini-dev/vaulter@v1
  with:
    backend: ${{ secrets.VAULTER_BACKEND }}
    project: my-app
    environment: prd
    export-to-env: true  # Makes vars available in subsequent steps
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}

- run: echo "Database is $DATABASE_URL"  # Available!

Action Inputs

Input	Required	Default	Description
`backend`	✓	-	S3 connection string
`project`	✓	-	Project name
`environment`	✓	-	Environment (dev/stg/prd)
`service`		-	Service (monorepo)
`outputs`		`env`	Comma-separated outputs
`k8s-namespace`		`default`	K8s namespace
`export-to-env`		`false`	Export to GITHUB_ENV
`mask-values`		`true`	Mask secrets in logs

Action Outputs

Output	Description
`env-file`	Path to .env file
`k8s-secret-file`	Path to K8s Secret YAML
`k8s-configmap-file`	Path to K8s ConfigMap YAML
`helm-values-file`	Path to Helm values file
`tfvars-file`	Path to .tfvars file
`vars-count`	Number of variables
`vars-json`	JSON array of variable names

CLI in CI/CD

You can also use the CLI directly:

- name: Pull and build
  env:
    VAULTER_PASSPHRASE: ${{ secrets.VAULTER_PASSPHRASE }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  run: |
    npx vaulter local sync -e prd
    npx vaulter local pull -e prd
    npx vaulter run -e prd -- pnpm build

Other Platforms

# GitLab CI
npx vaulter run -e ${CI_ENVIRONMENT_NAME} -- pnpm build

# Docker (build with secrets)
npx vaulter run -e prd -- docker build -t myapp .

# Terraform
vaulter export terraform -e prd > secrets.auto.tfvars

# Helm
vaulter export helm -e prd | helm upgrade myapp ./chart -f -

# Direct export
npx vaulter export k8s-secret -e prd | kubectl apply -f -

Kubernetes Runtime

When running in Kubernetes, env vars are already injected via ConfigMap/Secret. Vaulter's config() function automatically skips loading when it detects K8s:

import { config } from 'vaulter'

config() // Skips in K8s, loads files elsewhere

Detection: KUBERNETES_SERVICE_HOST environment variable is set by K8s automatically.

Monorepo Support

Auto-detects NX, Turborepo, Lerna, pnpm, Yarn workspaces, Rush.

vaulter service list                       # List discovered services
vaulter plan -e dev -s api                 # Plan changes for specific service
vaulter apply -e dev -s api               # Apply planned changes
vaulter export shell -e dev -s api         # Export with shared inheritance
vaulter export shell -e dev --shared       # Export only shared variables

Shared Variables Inheritance

When exporting for a specific service, shared variables are automatically included:

# Shared vars: NODE_ENV=development, LOG_LEVEL=debug
# API service vars: PORT=3000, LOG_LEVEL=info

vaulter export shell -e dev -s api
# Output: NODE_ENV=development, LOG_LEVEL=info, PORT=3000
# (service vars override shared vars with same key)

# To export without inheritance:
vaulter export shell -e dev -s api --no-shared

Output Targets (Multi-Framework)

One config → multiple .env files. Works with any framework: Next.js, NestJS, Express, NX, Turborepo, etc.

The Problem

Different apps need different variables in different places:

apps/
├── web/          # Next.js needs .env.local with NEXT_PUBLIC_*
├── api/          # NestJS needs .env with DATABASE_*, JWT_*
└── admin/        # Needs everything

The Solution

Define outputs once, pull everywhere:

# .vaulter/config.yaml
outputs:
  web:
    path: apps/web
    filename: .env.local
    include: [NEXT_PUBLIC_*]      # Only public vars

  api:
    path: apps/api
    include: [DATABASE_*, JWT_*]  # Only backend vars
    exclude: [*_DEV]              # No dev-only vars

  admin: apps/admin               # Shorthand: all vars

# Shared across all outputs (inherited automatically)
shared:
  include: [NODE_ENV, LOG_LEVEL, SENTRY_*]

Pull to All Outputs

# Pull to all outputs at once
vaulter local pull --all

# Result:
# ✓ web: apps/web/.env.local (5 vars)
# ✓ api: apps/api/.env (12 vars)
# ✓ admin: apps/admin/.env (25 vars)

Pull to Specific Output

# Pull only web
vaulter local pull --output web

# Preview without writing
vaulter local pull --all --dry-run

How It Works

┌─────────────────────────────────────────────────────────┐
│                    Backend (S3)                         │
│  DATABASE_URL, JWT_SECRET, NEXT_PUBLIC_API, LOG_LEVEL   │
└────────────────────────┬────────────────────────────────┘
                         │
              vaulter local pull --all
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   ┌──────────┐    ┌──────────┐    ┌──────────┐
   │   web    │    │   api    │    │  admin   │
   │ .env.local│   │  .env    │    │  .env    │
   │          │    │          │    │          │
   │ LOG_LEVEL│    │ LOG_LEVEL│    │ LOG_LEVEL│  ← shared (inherited)
   │ NEXT_*   │    │ DATABASE_│    │ ALL VARS │  ← filtered by include/exclude
   └──────────┘    │ JWT_*    │    └──────────┘
                   └──────────┘

Pattern Syntax

Pattern	Matches
`NEXT_PUBLIC_*`	`NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_GA_ID`
`*_SECRET`	`JWT_SECRET`, `API_SECRET`
`DATABASE_*`	`DATABASE_URL`, `DATABASE_HOST`
`*_URL`	`API_URL`, `DATABASE_URL`, `REDIS_URL`

Inheritance

By default, shared.include vars are added to ALL outputs. Override with inherit: false:

outputs:
  isolated-app:
    path: apps/isolated
    inherit: false           # No shared vars
    include: [ISOLATED_*]

Local Overrides (Dev Environment) - OFFLINE FIRST

vaulter local pull and local .env generation are 100% OFFLINE - no backend calls.

Works entirely from local files in .vaulter/local/. This is the primary workflow for day-to-day development: edit local overrides, run vaulter local pull, and only sync when needed.

Quick Reference

Command	What it does	Backend?
`vaulter local pull`	Generate .env files from local	❌ OFFLINE
`vaulter local push --all`	Send local → backend	✅ Backend
`vaulter local sync`	Download backend → local	✅ Backend
`vaulter local set`	Write local override to `.vaulter/local/`	❌ OFFLINE
`vaulter local diff`	Compare local overrides vs base env	❌ OFFLINE

Workflow

┌─────────────────────────────────────────────────────┐
│              LOCAL DEVELOPMENT                       │
│  1. Edit .vaulter/local/*.env                       │
│  2. vaulter local pull       → Generate .env       │
│  3. Develop...                                       │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│              SHARE WITH TEAM                         │
│  vaulter local push --all  → Upload to backend      │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│              NEW TEAM MEMBER                         │
│  1. git clone <repo>                                │
│  2. vaulter local sync     → Download from backend  │
│  3. vaulter local pull      → Generate .env        │
└─────────────────────────────────────────────────────┘

For monorepos, use --service <name> on local set, local delete, local diff, and local push (without --all), unless the CLI can infer the service from your current directory (or the monorepo has only one service).

File Structure

.vaulter/local/
├── configs.env           # Shared configs (all services)
├── secrets.env           # Shared secrets (all services)
└── services/             # Monorepo only
    ├── web/
    │   ├── configs.env   # web-specific configs
    │   └── secrets.env   # web-specific secrets
    └── api/
        ├── configs.env
        └── secrets.env

Merge Order (Per Output)

Priority: shared vars < service-specific vars

For each output target, vaulter merges:

Shared vars from .vaulter/local/{configs,secrets}.env
Service-specific vars from .vaulter/local/services/{service}/*.env

Example:

20 shared vars + 3 service-specific = 23 vars for that service
NOT all vars from all services merged together!

CLI Commands

# === EDIT LOCALLY ===
vaulter local set --shared DEBUG::true     # shared config
vaulter local set --shared API_KEY=xxx     # shared secret
vaulter local set PORT::3001                # service config (inferred from cwd in monorepo)
vaulter local set DB_URL=xxx -s api        # service secret
# In service directories, `-s` is usually auto-inferred.
# If the repo has only one service, `-s` is inferred automatically too.

# === GENERATE .ENV FILES [OFFLINE] ===
vaulter local pull
# Output: "svc-auth: 23 vars (21 shared + 2 service)"

# === SHARE WITH TEAM ===
vaulter local push --all                   # Upload entire structure

# === GET TEAM'S CHANGES ===
vaulter local sync                         # Download from backend
vaulter local pull                        # Generate .env files

# === OTHER ===
vaulter local diff                         # Show differences
vaulter local status                       # Show summary

Section-Aware .env Management

Vaulter uses section-aware mode by default when writing .env files. This preserves your custom variables while managing backend variables separately.

# Your variables (NEVER touched by vaulter)
MY_LOCAL_VAR=something
CUSTOM_DEBUG=true
MY_PORT_OVERRIDE=3001

# --- VAULTER MANAGED (do not edit below) ---
DATABASE_URL=postgres://...
API_KEY=sk-xxx
NODE_ENV=production
# --- END VAULTER ---

How it works:

Location	Behavior
Above marker	Preserved - your custom vars, never modified
Between markers	Managed - vaulter controls this section
Below end marker	Preserved - any trailing content

CLI options:

# Section-aware pull (default)
vaulter local pull

# Overwrite entire file (ignores sections)
vaulter local pull --overwrite

Programmatic API:

import {
  syncVaulterSection,
  getUserVarsFromEnvFile,
  setInEnvFile
} from 'vaulter'

// Sync only the managed section (preserves user vars)
syncVaulterSection('/app/.env', {
  DATABASE_URL: 'postgres://...',
  API_KEY: 'sk-xxx'
})

// Read only user-defined vars (above the marker)
const userVars = getUserVarsFromEnvFile('/app/.env')
// { MY_LOCAL_VAR: 'something', CUSTOM_DEBUG: 'true' }

// Add var to user section (above marker)
setInEnvFile('/app/.env', 'MY_VAR', 'value', true)

Use cases:

Local debugging: Add DEBUG=true above the marker, it stays after vaulter local pull
Port conflicts: Override PORT=3001 locally without affecting teammates
Feature flags: Test with FEATURE_X_ENABLED=true without touching backend
Framework vars: Keep .env.local compatible with Next.js/Vite expectations

API Usage

import { VaulterClient, loadConfig } from 'vaulter'

const client = new VaulterClient({ config: loadConfig() })
await client.connect()

await client.set({ key: 'API_KEY', value: 'sk-xxx', project: 'my-project', environment: 'prd' })
const value = await client.get('API_KEY', 'my-project', 'prd')
const vars = await client.list({ project: 'my-project', environment: 'prd' })

await client.disconnect()

Smart Config (Auto-Detection)

The config() function auto-detects your environment and loads the appropriate files:

import { config } from 'vaulter'

// Auto-detect environment and load appropriate files
const result = config()

// With options
config({
  mode: 'auto',        // 'auto' | 'local' | 'deploy' | 'skip'
  environment: 'dev',  // Override environment (dev, stg, prd)
  service: 'api',      // For monorepo service-specific vars
  verbose: true,       // Debug output
})

Environment Detection:

Environment	Detection	Behavior
Kubernetes	`KUBERNETES_SERVICE_HOST` set	Skip loading (vars injected via ConfigMap/Secret)
CI/CD	`CI=true`, `GITHUB_ACTIONS`, etc.	Load from `.vaulter/deploy/`
Local	Default	Load from `.vaulter/local/` (configs.env + secrets.env)

Why this matters:

K8s: Env vars are already injected, no file loading needed
CI/CD: Uses committed configs + secrets pulled from backend
Local: Developer's machine-specific .env file (gitignored)

Auto-load (dotenv compatible)

import 'vaulter/load'  // Auto-loads .env into process.env

Runtime Loader (No .env Files)

Load secrets directly from the backend at application startup - no .env files, no Kubernetes ConfigMaps/Secrets needed.

Quick Start

// Option 1: Simple import (like dotenv/config)
import 'vaulter/load'

// Option 2: Side-effect import with full path
import 'vaulter/runtime/load'

// Option 3: With options
import { loadRuntime } from 'vaulter'

await loadRuntime({
  environment: 'prd',
  service: 'api',        // Optional: for monorepos
  required: true         // Default: true in prd, false otherwise
})

// Option 4: Using config() with backend source
import { config } from 'vaulter'

await config({ source: 'backend' })

// Now process.env has all your secrets!
console.log(process.env.DATABASE_URL)

How It Works

Reads .vaulter/config.yaml to find backend URL
Loads encryption key (per-environment support)
Fetches secrets from S3/MinIO backend
Populates process.env

Configuration

# .vaulter/config.yaml
project: my-app
backend:
  url: s3://my-bucket/secrets

# Runtime detects environment from NODE_ENV or config
default_environment: dev

Options

Option	Type	Default	Description
`environment`	string	`NODE_ENV` or `dev`	Target environment
`project`	string	from config	Project name
`service`	string	-	Service name (monorepo)
`required`	boolean	`true` in prd	Throw on failure
`override`	boolean	`false`	Override existing env vars
`includeShared`	boolean	`true`	Include shared vars (monorepo)
`filter.include`	string[]	`[]`	Glob patterns to include
`filter.exclude`	string[]	`[]`	Glob patterns to exclude
`verbose`	boolean	`false`	Enable logging

Per-Environment Keys

Runtime loader automatically uses per-environment keys:

# Set env-specific keys
export VAULTER_KEY_DEV="dev-secret"
export VAULTER_KEY_PRD="prd-secret"

# Or generate key files
vaulter key generate --env prd

Use Cases

Kubernetes without ConfigMaps/Secrets:

# deployment.yaml - No configMapRef/secretRef needed!
env:
  - name: VAULTER_KEY_PRD
    valueFrom:
      secretKeyRef:
        name: vaulter-key
        key: prd
  - name: VAULTER_BACKEND
    value: "s3://my-bucket/secrets"

// app.ts - Secrets loaded at startup
import 'vaulter/runtime/load'
// process.env.DATABASE_URL is now available

Lambda/Serverless:

import { loadRuntime } from 'vaulter'

export const handler = async (event) => {
  await loadRuntime({ environment: 'prd' })
  // Use secrets from process.env
}

Library API

import { loadRuntime, isRuntimeAvailable, getRuntimeInfo } from 'vaulter'

// Check if runtime config exists
if (isRuntimeAvailable()) {
  const info = await getRuntimeInfo()
  console.log(info.project, info.environment, info.backend)
}

// Load with callbacks
const result = await loadRuntime({
  environment: 'prd',
  onLoaded: (r) => console.log(`Loaded ${r.varsLoaded} vars in ${r.durationMs}ms`),
  onError: (e) => console.error('Failed:', e.message)
})

MCP Server

Claude AI integration via Model Context Protocol. 17 Tools | 4 Resources | 5 Prompts.

vaulter mcp

Claude Desktop

{
  "mcpServers": {
    "vaulter": {
      "command": "vaulter",
      "args": ["mcp", "--cwd", "/path/to/project"]
    }
  }
}

Tools (17)

Tool Architecture: Each tool is action-based (one tool per domain with action parameter).

Category	Tool	Actions / Description
Mutation Flow	`vaulter_change`	set, delete, move, import (writes local state only)
	`vaulter_plan`	Compute diff local vs backend, generate plan artifact
	`vaulter_apply`	Execute plan, push changes to backend
	`vaulter_run`	Execute command with loaded variables
Read	`vaulter_get`	Get single var or multi-get via `keys[]`
	`vaulter_list`	List vars with optional filter
	`vaulter_search`	Search by pattern or compare environments
	`vaulter_diff`	Quick diff without plan artifacts
Status	`vaulter_status`	scorecard, vars, audit, drift, inventory
Export	`vaulter_export`	k8s-secret, k8s-configmap, helm, terraform, env, shell, json
Keys	`vaulter_key`	generate, list, show, export, import, rotate
Local Dev	`vaulter_local`	pull, push, push-all, sync, set, delete, diff, status, shared-set, shared-delete, shared-list
Backup	`vaulter_snapshot`	create, list, restore, delete
	`vaulter_versions`	list, get, rollback
Setup	`vaulter_init`	Initialize project
	`vaulter_services`	Discover monorepo services
Danger	`vaulter_nuke`	Preview backend deletion (CLI-only execution)

Resources (4)

Static data views (no input required). For actions with parameters, use tools.

URI	Description
`vaulter://instructions`	Read first! s3db.js architecture + tool overview
`vaulter://tools-guide`	Which tool to use for each scenario
`vaulter://config`	Project configuration (YAML)
`vaulter://services`	Monorepo services list

Prompts (5)

Pre-configured workflows for common tasks.

Prompt	Description
`setup_project`	Initialize new vaulter project
`deploy_secrets`	Deploy to Kubernetes
`compare_environments`	Compare dev vs prd
`rotation_workflow`	Check/rotate/report on rotation
`local_dev_workflow`	Manage local dev overrides (shared + service)

Full MCP documentation: See docs/MCP.md for complete tool reference with parameters.

Shell (Interactive Terminal)

vaulter shell              # Secrets Explorer (default)
vaulter shell menu         # Menu
vaulter shell audit        # Audit log viewer
vaulter shell keys         # Key manager

SYNC Column (Secrets Explorer)

Shows local .env sync status vs backend:

Icon	Status	Meaning
`✓`	synced	Local value = backend value
`≠`	modified	Local value differs from backend
`−`	missing	Exists in backend, not in local .env
`+`	local-only	Exists only in local .env

Shortcuts

Global: q quit · ESC back · ↑↓ navigate

Screen	Shortcuts
Menu	`1` `2` `3` quick access to screens
Explorer	`r` refresh · `v` toggle values · `Tab` cycle env · `j/k` vim nav
Audit	`o` filter op · `s` filter source · `/` search · `c` clear
Keys	`r` refresh · `c` toggle config

Pre-built Binaries

Download from Releases:

Platform	Binary
Linux x64/ARM64	`vaulter-linux-x64`, `vaulter-linux-arm64`
macOS x64/ARM64	`vaulter-macos-x64`, `vaulter-macos-arm64`
Windows x64	`vaulter-win-x64.exe`

License

Keywords

FAQs

What is vaulter?

Is vaulter well maintained?

Package last updated on 02 Apr 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

vaulter

vaulter

Multi-Backend Environment & Secrets Manager

Installation

Quick Start

Minimal

End-to-End (Monorepo, web + api)

🔄 Development Workflow

The Golden Rule

Directory Structure

.gitignore Setup

Daily Workflow

Environment Promotion Flow

Team Collaboration

MCP Tools for Workflow

What is Vaulter?

Quick Start (Local Development)

🩺 Health Check - Status

Runbook local (scripts/vaulter-verify-dev.sh)

Commands

Setup

Health

Mutations (change)

Plan & Apply

Recommended daily path

Export

Services (monorepo)

Audit & Rotation

Key Management

Run (Execute with Env Vars)

Run scripts via package.json

Security

Symmetric (Default)

Asymmetric (RSA/EC)

Per-Environment Keys

Shared Variables Key (Monorepo)

Configuration

Backend URLs

Local vs Deploy Structure

CI/CD

GitHub Action (Recommended)

Output Formats

Full Examples

Action Inputs

Action Outputs

CLI in CI/CD

Other Platforms

Kubernetes Runtime

Monorepo Support

Shared Variables Inheritance

Output Targets (Multi-Framework)

The Problem

The Solution

Pull to All Outputs

Pull to Specific Output

How It Works

Pattern Syntax

Inheritance

Local Overrides (Dev Environment) - OFFLINE FIRST

Quick Reference

Workflow

File Structure

Merge Order (Per Output)

CLI Commands

Section-Aware .env Management

API Usage

Smart Config (Auto-Detection)

Auto-load (dotenv compatible)

Runtime Loader (No .env Files)

Quick Start

How It Works

Configuration

Options

Per-Environment Keys

Use Cases

Library API

MCP Server

Claude Desktop

Tools (17)

Resources (4)

End-to-End (Monorepo, `web` + `api`)

Runbook local (`scripts/vaulter-verify-dev.sh`)

Mutations (`change`)