Quick Start

npm install -g vaulter

# Initialize project
vaulter init

# Set some secrets
vaulter set DATABASE_URL "postgres://localhost/mydb" -e dev
vaulter set API_KEY "sk-secret-key" -e dev

# Export to shell
eval $(vaulter export -e dev)

# Deploy to Kubernetes
vaulter k8s:secret -e prd | kubectl apply -f -

What's Inside

Highlights

Multi-Backend with Fallback

Configure multiple backends - vaulter tries each until one succeeds:

backend:
  urls:
    - s3://bucket/envs?region=us-east-1     # Primary (CI/CD)
    - file:///home/user/.vaulter-store       # Fallback (local dev)

Native Integrations

# Kubernetes - deploy secrets directly
vaulter k8s:secret -e prd | kubectl apply -f -

# Helm - generate values file
vaulter helm:values -e prd | helm upgrade myapp ./chart -f -

# Terraform - export as tfvars
vaulter tf:vars -e prd > terraform.tfvars

Unix Pipes

# Import from Vault
vault kv get -format=json secret/app | \
  jq -r '.data.data | to_entries | .[] | "\(.key)=\(.value)"' | \
  vaulter sync -e prd

# Export to kubectl
vaulter export -e prd --format=env | \
  kubectl create secret generic myapp --from-env-file=/dev/stdin

MCP Server for Claude

# Start MCP server
vaulter mcp

{
  "mcpServers": {
    "vaulter": {
      "command": "npx",
      "args": ["vaulter", "mcp"]
    }
  }
}

Dotenv Compatible

Drop-in replacement for dotenv - works with your existing setup:

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

// Or programmatically with options
import { loader } from 'vaulter'
loader({ path: '.env.local', override: true })

Commands

Core

Sync

Integrations

Utilities

Global Options

-p, --project <name>    Project name
-s, --service <name>    Service name (monorepos)
-e, --env <env>         Environment: dev, stg, prd, sbx, dr
-b, --backend <url>     Backend URL override
-k, --key <path|value>  Encryption key file path or raw key
-v, --verbose           Verbose output
--all                   All services (monorepo batch)
--dry-run               Preview without applying
--json                  JSON output
--force                 Skip confirmations

Configuration

Basic Config

# .vaulter/config.yaml
version: "1"

project: my-project
service: api  # optional

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

  # Or multiple with fallback
  urls:
    - s3://bucket/envs?region=us-east-1
    - file:///home/user/.vaulter-store

encryption:
  key_source:
    - env: VAULTER_KEY           # 1. Environment variable
    - file: .vaulter/.key        # 2. Local file
    - s3: s3://keys/vaulter.key  # 3. Remote S3

environments:
  - dev
  - stg
  - prd

default_environment: dev

Sync Settings

Sync merges local and remote variables. Conflicts are resolved by sync.conflict.

sync:
  conflict: local   # local | remote | prompt | error
  ignore:
    - "PUBLIC_*"
  required:
    dev:
      - DATABASE_URL

Notes:

• prompt and error will stop the sync if conflicts are detected.
• When reading from stdin, sync only updates the backend (local file is not changed).

Hooks

hooks:
  pre_sync: "echo pre sync"
  post_sync: "echo post sync"
  pre_pull: "echo pre pull"
  post_pull: "echo post pull"

Environment Variable Expansion

Config values support ${VAR}, ${VAR:-default}, and $VAR:

backend:
  url: s3://${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}@bucket/envs
  # Or
  url: ${VAULTER_BACKEND_URL}

Local Override (config.local.yaml)

For credentials that should never be committed:

# .vaulter/config.local.yaml (gitignored)
backend:
  url: s3://real-key:real-secret@bucket/envs?region=us-east-1

Backend URLs

Encryption

All secrets are encrypted with AES-256-GCM before storage.

Key Sources

# 1. Environment variable (CI/CD)
export VAULTER_KEY="base64-encoded-32-byte-key"
vaulter export -e prd

# 2. Local file (development)
vaulter key generate -o .vaulter/.key

# 3. Remote S3 (production)
# Configured in config.yaml

You can also pass a key directly:

vaulter list -e prd --key .vaulter/.key

Security Settings

security:
  paranoid: true  # Fail if no encryption key is found
  auto_encrypt:
    patterns:
      - "*_KEY"
      - "*_SECRET"
      - "DATABASE_URL"

auto_encrypt.patterns is used to classify secrets for integrations (K8s/Helm).

Monorepo Support

Vaulter auto-discovers services with .vaulter/ directories and supports config inheritance.

NX Monorepo

my-nx-workspace/
├── .vaulter/
│   ├── config.yaml              # Shared config (backend, encryption)
│   └── environments/
│       └── dev.env              # Shared dev vars
├── apps/
│   ├── web/
│   │   └── .vaulter/
│   │       ├── config.yaml      # extends: ../../../.vaulter/config.yaml
│   │       └── environments/
│   │           └── dev.env      # App-specific vars
│   └── api/
│       └── .vaulter/
│           ├── config.yaml
│           └── environments/
├── libs/                        # No .vaulter needed for libs
├── nx.json
└── package.json

# From workspace root
vaulter services                 # List: web, api

# Sync all apps
vaulter sync -e dev --all

# Sync single app (from root or app dir)
vaulter sync -e dev -s api
cd apps/api && vaulter sync -e dev

# NX run with env vars
eval $(vaulter export -e dev -s api) && nx serve api

Turborepo

my-turbo-monorepo/
├── .vaulter/
│   ├── config.yaml              # Root config
│   └── environments/
├── apps/
│   ├── web/
│   │   ├── .vaulter/
│   │   │   ├── config.yaml      # extends: ../../../.vaulter/config.yaml
│   │   │   └── environments/
│   │   └── package.json
│   └── docs/
│       └── .vaulter/
├── packages/                    # Shared packages (no .vaulter)
├── turbo.json
└── package.json

# List discovered services
vaulter services

# Batch sync before turbo build
vaulter sync -e prd --all && turbo build

# Export for specific app
cd apps/web && eval $(vaulter export -e dev)

# Turbo with env passthrough (turbo.json)
# { "pipeline": { "build": { "env": ["DATABASE_URL", "API_KEY"] } } }
vaulter export -e prd -s web --format=shell >> apps/web/.env
turbo build --filter=web

Service Config Inheritance

# apps/api/.vaulter/config.yaml
extends: ../../../.vaulter/config.yaml  # Inherit root config

service: api                            # Override service name

# Override or add service-specific settings
sync:
  required:
    prd:
      - DATABASE_URL
      - REDIS_URL

Commands

# List services
vaulter services

# Sync all services
vaulter sync -e dev --all

# Sync specific services (glob supported)
vaulter sync -e dev -s api,worker
vaulter sync -e dev -s "svc-*"

# Batch export
vaulter export -e prd --all --format=json

MCP Tools

CI/CD

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy secrets
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          npx vaulter k8s:secret -e prd | kubectl apply -f -

GitLab CI

deploy:
  script:
    - npx vaulter k8s:secret -e prd | kubectl apply -f -
  variables:
    VAULTER_KEY: $VAULTER_KEY

Security Best Practices

Files to .gitignore

.vaulter/.key
.vaulter/config.local.yaml
**/config.local.yaml
.env
.env.*

API Usage

import { VaulterClient, loadConfig } from 'vaulter'

const config = loadConfig()
const client = new VaulterClient({ config })

await client.connect()

// Get
const value = await client.get('DATABASE_URL', 'my-project', 'prd')

// Set
await client.set({
  key: 'API_KEY',
  value: 'sk-secret',
  project: 'my-project',
  environment: 'prd'
})

// List
const vars = await client.list({
  project: 'my-project',
  environment: 'prd'
})

// Export
const envVars = await client.export('my-project', 'prd')

await client.disconnect()

Comparison

Numbers

Pre-built Binaries

Download from Releases:

License

MIT © Forattini