Installation

# One-liner (recommended)
curl -fsSL https://raw.githubusercontent.com/forattini-dev/vaulter/main/install.sh | sh

# Or via npm/pnpm
npm install -g vaulter
pnpm add -g vaulter

Quick Start

# Initialize project
vaulter init

# Set secrets (encrypted, synced to backend)
vaulter set DATABASE_URL="postgres://localhost/mydb" -e dev

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

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

Table of Contents

• Why Vaulter?
• Security
• Daily Use
• Audit & Compliance
• Secret Rotation
• CI/CD
• Configuration
• Integrations
• Monorepo Support
• API Usage
• MCP Server

Why Vaulter?

The Problem

Environment variables and secrets are scattered across .env files, CI/CD settings, cloud consoles, and team Slack messages. This creates:

• Security gaps: Secrets in plaintext files, git history, or shared docs
• Sync issues: "Works on my machine" because .env files differ
• Deploy friction: Manual copy-paste between environments
• Audit blindness: No idea who changed what, when

The Solution

Vaulter centralizes all environment variables in encrypted storage (S3-compatible) while maintaining the simplicity of .env files:

Why Trust Vaulter?

1. Open source: All code is auditable
2. No lock-in: Your data lives in YOUR storage (S3, MinIO, R2, filesystem)
3. Standard encryption: AES-256-GCM, the same used by AWS, Google, and banks
4. Zero external dependencies: No SaaS, no API keys, no third-party services
5. Offline capable: Works with local filesystem backend

Security

Encryption Model

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

┌─────────────────────────────────────────────────────────────┐
│                     Your Machine                            │
│                                                             │
│  .env file ──► vaulter encrypt ──► encrypted blob ──► S3   │
│               (AES-256-GCM)         (unreadable)           │
│                                                             │
│  S3 ──► encrypted blob ──► vaulter decrypt ──► .env file   │
│         (unreadable)       (AES-256-GCM)                   │
└─────────────────────────────────────────────────────────────┘

What this means:

• The backend (S3, MinIO, etc.) only sees encrypted data
• Even with S3 access, secrets are unreadable without the key
• Each value is encrypted individually (field-level encryption)
• Authenticated encryption prevents tampering (GCM mode)

Key Management

Vaulter stores keys in ~/.vaulter/ directory (outside project) for security:

~/.vaulter/
├── projects/
│   └── <project-name>/
│       └── keys/
│           ├── master           # Private key (mode 600)
│           └── master.pub       # Public key (mode 644)
└── global/
    └── keys/                    # Shared across all projects
        ├── shared
        └── shared.pub

Key Commands

# Generate keys
vaulter key generate --name master                    # Symmetric key
vaulter key generate --name master --asymmetric       # RSA-4096 key pair
vaulter key generate --name master --asym --alg ec-p256  # EC P-256 key pair
vaulter key generate --name shared --global           # Global key (all projects)

# List and show keys
vaulter key list                      # List all keys (project + global)
vaulter key show --name master        # Show key details

# Export/import for deployment
vaulter key export --name master -o keys.enc    # Export encrypted bundle
vaulter key import -f keys.enc                  # Import on another machine

# Set VAULTER_EXPORT_PASSPHRASE to encrypt the bundle with custom passphrase

Configuration with key_name

The simplest way to use keys is via key_name resolution:

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

Legacy Key Sources (still supported)

You can also specify explicit key sources:

encryption:
  key_source:
    - env: VAULTER_KEY           # 1. Environment variable (CI/CD)
    - file: .vaulter/.key        # 2. Local file (development)
    - s3: s3://keys/vaulter.key  # 3. Remote S3 (shared teams)

Option 1: Environment Variable (Recommended for CI/CD)

# Generate a key
vaulter key generate --name master

# Set in CI/CD secrets from the generated key
export VAULTER_KEY=$(cat ~/.vaulter/projects/myproject/keys/master)

Pros: Key never in project directory, rotates easily via CI/CD secret rotation Use case: GitHub Actions, GitLab CI, Jenkins

Option 2: key_name Resolution (Recommended for Development)

encryption:
  mode: asymmetric
  asymmetric:
    key_name: master    # Auto-resolves to ~/.vaulter/projects/<project>/keys/

Pros: Simple, keys stored securely outside project Use case: Local development, team workflows

Option 3: Remote S3 (Team Shared)

encryption:
  key_source:
    - s3: s3://company-keys/vaulter/project.key?region=us-east-1

Pros: Centralized key management, IAM-controlled access Use case: Teams, multiple developers needing same key

Asymmetric Key Encryption (RSA/EC)

For enhanced security with separate encrypt/decrypt permissions, Vaulter supports hybrid encryption using RSA or Elliptic Curve key pairs.

How It Works

┌────────────────────────────────────────────────────────────────┐
│                     Hybrid Encryption                          │
│                                                                │
│  Your secret ──► AES-256-GCM ──► Encrypted data               │
│                      │                                         │
│                      │ (random AES key)                        │
│                      ▼                                         │
│  Public key ──► RSA/EC encrypt ──► Encrypted AES key          │
│                                                                │
│  Stored: { encrypted_key + encrypted_data + metadata }        │
│                                                                │
│  Decryption requires: Private key + Encrypted blob            │
└────────────────────────────────────────────────────────────────┘

Benefits:

• Separation of duties: Public key can only encrypt, private key can decrypt
• CI/CD security: Give CI/CD only the public key - it can write but not read secrets
• Production isolation: Only production has the private key for decryption

Generate Key Pair

# RSA 4096-bit (default, most compatible)
vaulter key generate --name master --asymmetric

# RSA 2048-bit (faster, less secure)
vaulter key generate --name master --asym --algorithm rsa-2048

# Elliptic Curve P-256 (modern, fast)
vaulter key generate --name master --asym --alg ec-p256

# Elliptic Curve P-384 (stronger EC)
vaulter key generate --name master --asym --alg ec-p384

# Global key (shared across all projects)
vaulter key generate --name shared --global --asymmetric

Output:

✓ Generated rsa-4096 key pair: master
  Private: ~/.vaulter/projects/my-project/keys/master (mode 600 - keep secret!)
  Public:  ~/.vaulter/projects/my-project/keys/master.pub (mode 644)

To use these keys in config.yaml:
  encryption:
    mode: asymmetric
    asymmetric:
      algorithm: rsa-4096
      key_name: master

Configuration

# .vaulter/config.yaml
encryption:
  mode: asymmetric              # Enable asymmetric mode
  asymmetric:
    algorithm: rsa-4096         # or rsa-2048, ec-p256, ec-p384
    key_name: master            # Uses ~/.vaulter/projects/<project>/keys/master[.pub]
    # Or for global keys:
    # key_name: global:master   # Uses ~/.vaulter/global/keys/master[.pub]

# Alternative: explicit key sources (for CI/CD or custom paths)
# encryption:
#   mode: asymmetric
#   asymmetric:
#     algorithm: rsa-4096
#     public_key:
#       - file: /path/to/master.pub
#       - env: VAULTER_PUBLIC_KEY
#     private_key:
#       - file: /path/to/master
#       - env: VAULTER_PRIVATE_KEY

Supported Algorithms

Use Case: Secure CI/CD Pipeline

┌─────────────────────────────────────────────────────────────┐
│ Development                                                  │
│   Developers have BOTH keys → can read and write secrets    │
│   vaulter set API_KEY="..." -e dev                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ CI/CD (GitHub Actions, Jenkins, etc.)                        │
│   Only PUBLIC key → can write NEW secrets, cannot read      │
│   Useful for automated secret rotation scripts              │
│                                                             │
│   env:                                                      │
│     VAULTER_PUBLIC_KEY: ${{ secrets.VAULTER_PUBLIC_KEY }}   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Production                                                   │
│   Only PRIVATE key → can read secrets at runtime            │
│                                                             │
│   env:                                                      │
│     VAULTER_PRIVATE_KEY: ${{ secrets.VAULTER_PRIVATE_KEY }} │
│                                                             │
│   # Application reads secrets at startup                    │
│   eval $(vaulter export -e prd)                             │
└─────────────────────────────────────────────────────────────┘

Environment Variables

Advanced Security Configurations

AWS KMS Integration (Planned)

For enterprises requiring HSM-backed keys:

encryption:
  kms:
    key_id: arn:aws:kms:us-east-1:123456789:key/abc-123
    # Key never leaves AWS KMS
    # Envelope encryption: KMS encrypts the data key

How it works:

1. Vaulter generates a data encryption key (DEK)
2. DEK encrypts your secrets locally
3. AWS KMS encrypts the DEK (envelope encryption)
4. Only encrypted DEK + encrypted secrets are stored
5. Decryption requires both KMS access AND S3 access

Threat Model

Security Best Practices

# ✅ DO
vaulter key generate                    # Random 256-bit key
echo ".vaulter/.key" >> .gitignore      # Never commit keys
export VAULTER_KEY="${{ secrets.KEY }}" # CI/CD secrets

# ❌ DON'T
echo "password123" > .vaulter/.key      # Weak key
git add .vaulter/.key                   # Exposed key
vaulter set KEY=val --key "hardcoded"   # Key in command history

Daily Use

Workflow Overview

# Morning: sync with team's changes
vaulter pull -e dev

# During development: add new variable
vaulter set NEW_API_KEY="sk-xxx" -e dev

# End of day: push changes
vaulter push -e dev

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

Commands Reference

Core Commands

Sync Commands

Integration Commands

Audit Commands

Rotation Commands

Set Command Syntax

# Secrets (encrypted, synced to backend)
vaulter set KEY=value                    # Single secret
vaulter set A=1 B=2 C=3 -e dev           # Batch secrets
vaulter set KEY:=123                     # Typed (number/boolean)

# Configs (plain text in split mode)
vaulter set PORT::3000 HOST::localhost   # Configs

Global Options

-p, --project <name>    Project name
-s, --service <name>    Service name (monorepos)
-e, --env <env>         Environment name (as defined in config)
-b, --backend <url>     Backend URL override
-k, --key <path|value>  Encryption key
-f, --file <path>       Input file path
-o, --output <path>     Output file path
-n, --namespace <name>  Kubernetes namespace
    --format <fmt>      Output format (shell/json/yaml/env/tfvars/docker-args)
-v, --verbose           Verbose output (shows values)
    --dry-run           Preview without applying
    --json              JSON output
    --force             Skip confirmations
    --all               Apply to all services in monorepo

Flexible Environment Names

Vaulter lets you define your own environment names. Use whatever convention fits your workflow:

# Short names (default)
environments: [dev, stg, prd]

# Full names
environments: [development, staging, production]

# Custom names
environments: [local, homolog, qa, uat, prod]

# Brazilian pattern
environments: [dev, homolog, prd]

All commands use -e with your custom names:

vaulter list -e homolog
vaulter pull -e development
vaulter k8s:secret -e uat | kubectl apply -f -

Audit & Compliance

Vaulter includes built-in audit logging to track every change to your secrets. Essential for compliance (SOC2, HIPAA, PCI-DSS) and debugging "who changed what, when".

Why Audit?

┌─────────────────────────────────────────────────────────────────┐
│                    Without Audit Logging                        │
│                                                                 │
│  Developer: "Who deleted the API_KEY in production?"            │
│  Team: 🤷 "No idea, check git blame? It's not in the repo..."  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     With Vaulter Audit                          │
│                                                                 │
│  $ vaulter audit list -e prd --pattern "API_KEY"                │
│                                                                 │
│  TIMESTAMP            USER      OP      KEY      ENV   SRC      │
│  2025-01-15 14:32:01  john      delete  API_KEY  prd   cli      │
│  2025-01-10 09:15:22  jane      set     API_KEY  prd   sync     │
│  2025-01-05 11:00:00  deploy    set     API_KEY  prd   ci       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Configuration

# .vaulter/config.yaml
audit:
  enabled: true              # Enable audit logging (default: true)
  retention_days: 90         # Auto-cleanup entries older than N days
  mask_values: true          # Mask values in logs (show: sk-1234****5678)
  include_values: false      # Include actual values (⚠️ security risk)

Commands

List Audit Entries

# List recent entries (default: 50)
vaulter audit list -e prd

# Filter by user
vaulter audit list -e prd --user john

# Filter by operation
vaulter audit list -e prd --operation delete

# Filter by key pattern (supports wildcards)
vaulter audit list -e prd --pattern "DATABASE_*"

# Filter by date range
vaulter audit list -e prd --since "2025-01-01" --until "2025-01-15"

# Filter by source
vaulter audit list -e prd --source ci

# Show all environments
vaulter audit list --all-envs

# JSON output for scripting
vaulter audit list -e prd --json

# Combine filters
vaulter audit list -e prd --user deploy --operation set --limit 100

Output:

TIMESTAMP            USER          OP        KEY                       ENV   SRC
2025-01-15 14:32:01  john          delete    API_KEY                   prd   cli
2025-01-15 14:30:00  jane          set       DATABASE_URL              prd   cli
2025-01-15 10:00:00  github-ci     push      *                         prd   ci
2025-01-14 16:45:22  jane          sync      *                         prd   cli

Showing 4 entries

Show Entry Details

# Get full details of a specific entry
vaulter audit show <entry-id>

Output:

  ID:          abc123def456
  Timestamp:   2025-01-15 14:32:01
  User:        john
  Operation:   delete
  Key:         API_KEY
  Project:     my-project
  Environment: prd
  Source:      cli
  Previous:    sk-1234****5678
  Metadata:    {"reason": "rotating key"}

Audit Statistics

# View summary statistics
vaulter audit stats -e prd

Output:

Audit Statistics for my-project/prd
════════════════════════════════════════
Total entries: 1,247
Date range:    2024-10-15 09:00:00 to 2025-01-15 14:32:01

By Operation:
  set          892
  delete       124
  sync         156
  push         75

By User:
  jane                 456
  john                 321
  github-ci            470

By Source:
  cli        645
  ci         470
  sync       132

Cleanup Old Entries

# Cleanup entries older than retention_days (from config)
vaulter audit cleanup

# Override retention period
vaulter audit cleanup --retention 30

# Dry-run to see what would be deleted
vaulter audit cleanup --retention 30 --dry-run

Automatic Audit Logging

Audit entries are created automatically for all write operations:

Sources

The source field indicates where the operation originated:

Compliance Tips

# Export audit log for compliance review
vaulter audit list --all-envs --json > audit-report-$(date +%Y%m).json

# Monitor production changes
vaulter audit list -e prd --since "$(date -d 'yesterday' +%Y-%m-%d)"

# Alert on deletions
vaulter audit list -e prd --operation delete --json | jq '.entries | length'

Secret Rotation

Regular secret rotation is a security best practice. Vaulter tracks rotation schedules and helps you identify secrets that need attention.

Why Rotate?

• Limit exposure: If a key is compromised, damage is time-limited
• Compliance: Many standards require periodic rotation (PCI-DSS: 90 days)
• Access control: Rotated keys invalidate old access
• Audit trail: Clear history of when credentials changed

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                    Rotation Workflow                            │
│                                                                 │
│  1. vaulter rotation list        → See what needs rotation      │
│                                                                 │
│  KEY            ENV   LAST ROTATED    ROTATE AFTER    STATUS    │
│  DATABASE_URL   prd   45 days ago     90 days         ✓ OK      │
│  API_KEY        prd   120 days ago    90 days         ⚠ OVERDUE │
│  JWT_SECRET     prd   never           90 days         ⚠ OVERDUE │
│                                                                 │
│  2. Manually rotate the credential in the external service      │
│                                                                 │
│  3. vaulter set API_KEY="new-value" -e prd                      │
│     → Automatically updates rotatedAt timestamp                 │
│                                                                 │
│  4. vaulter rotation run -e prd --clear                         │
│     → Clears rotateAfter for updated keys (fresh start)         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Configuration

# .vaulter/config.yaml
encryption:
  rotation:
    enabled: true          # Enable rotation tracking
    interval_days: 90      # Default rotation interval
    patterns:              # Keys that should be rotated
      - "*_KEY"
      - "*_SECRET"
      - "*_TOKEN"
      - "*_PASSWORD"
      - "DATABASE_URL"
      - "REDIS_URL"

Commands

List Rotation Status

# Show rotation status for all secrets
vaulter rotation list -e prd

# Check all environments
vaulter rotation list --all-envs

# Filter overdue only
vaulter rotation list -e prd --overdue

# Custom interval check
vaulter rotation list -e prd --days 30

# JSON output
vaulter rotation list -e prd --json

Output:

Rotation Status for my-project/prd (default: 90 days)

KEY               LAST ROTATED         ROTATE AFTER         STATUS
DATABASE_URL      2024-12-01           2025-03-01           ✓ OK (45 days)
API_KEY           2024-09-15           2024-12-14           ⚠ OVERDUE (32 days)
JWT_SECRET        never                —                    ⚠ NEVER ROTATED
REDIS_URL         2024-11-20           2025-02-18           ✓ OK (34 days)

Summary: 4 secrets, 2 overdue, 1 never rotated

Run Rotation Check

# Interactive rotation workflow
vaulter rotation run -e prd

# Clear rotation schedule for already-rotated keys
vaulter rotation run -e prd --clear

# Set new interval
vaulter rotation run -e prd --interval 60

# Dry-run
vaulter rotation run -e prd --dry-run

Interactive Output:

Checking rotation status for my-project/prd...

⚠ Found 2 secrets needing rotation:

  API_KEY (overdue by 32 days)
    Last rotated: 2024-09-15
    Rotate after: 2024-12-14

  JWT_SECRET (never rotated)
    Set a rotation schedule? [Y/n]: y
    Rotation interval (days) [90]: 90
    ✓ Scheduled rotation for 2025-04-15

To update a rotated secret:
  vaulter set API_KEY="new-value" -e prd

After rotating, clear the schedule:
  vaulter rotation run -e prd --clear

Schedule Rotation

When you set a new value, Vaulter automatically tracks when it was last changed:

# Set new value (automatically updates rotatedAt)
vaulter set API_KEY="sk-new-rotated-key" -e prd

# Verify rotation was tracked
vaulter rotation list -e prd --pattern "API_KEY"

Output:

KEY       LAST ROTATED         ROTATE AFTER    STATUS
API_KEY   just now             2025-04-15      ✓ OK (90 days)

Rotation Metadata

Each secret tracks rotation metadata:

View with:

vaulter get API_KEY -e prd --json | jq '.metadata'

CI/CD Integration

# GitHub Actions - Weekly rotation check
name: Secret Rotation Check
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am

jobs:
  check-rotation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check for overdue secrets
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          OVERDUE=$(npx vaulter rotation list -e prd --json | jq '.overdue')
          if [ "$OVERDUE" -gt 0 ]; then
            echo ":⚠️:$OVERDUE secrets are overdue for rotation!"
            npx vaulter rotation list -e prd
            exit 1
          fi
          echo "✓ All secrets are within rotation policy"

Compliance Matrix

CI/CD

GitHub Actions (Quick Start)

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy secrets to Kubernetes
        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 -

GitHub Actions (Complete Example)

name: Deploy to Kubernetes
on:
  push:
    branches: [main, develop]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'dev'
        type: choice
        options: [dev, stg, prd]

env:
  VAULTER_VERSION: '1.0.1'

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'prd') || 'dev' }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install Vaulter
        run: npm install -g vaulter@${{ env.VAULTER_VERSION }}

      - name: Configure kubectl
        uses: azure/k8s-set-context@v4
        with:
          kubeconfig: ${{ secrets.KUBECONFIG }}

      - 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: |
          ENV=${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'prd') || 'dev' }}

          # Deploy K8s Secret
          vaulter k8s:secret -e $ENV -n my-namespace | kubectl apply -f -

          # Deploy ConfigMap (non-sensitive config)
          vaulter k8s:configmap -e $ENV -n my-namespace | kubectl apply -f -

          # Verify deployment
          kubectl get secret,configmap -n my-namespace

      - name: Restart Deployment
        run: |
          kubectl rollout restart deployment/my-app -n my-namespace
          kubectl rollout status deployment/my-app -n my-namespace --timeout=120s

GitHub Actions (Monorepo with Services)

name: Deploy Service
on:
  push:
    branches: [main]
    paths:
      - 'apps/svc-*/**'

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.changes.outputs.services }}
    steps:
      - uses: actions/checkout@v4
      - id: changes
        run: |
          # Detect which services changed
          SERVICES=$(git diff --name-only HEAD~1 | grep '^apps/svc-' | cut -d'/' -f2 | sort -u | jq -R -s -c 'split("\n")[:-1]')
          echo "services=$SERVICES" >> $GITHUB_OUTPUT

  deploy:
    needs: detect-changes
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: ${{ fromJson(needs.detect-changes.outputs.services) }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy ${{ matrix.service }}
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          # Deploy secrets for specific service
          vaulter k8s:secret -e prd -s ${{ matrix.service }} | kubectl apply -f -

GitHub Actions (Using Binary for Speed)

name: Deploy (Fast)
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Vaulter Binary
        run: |
          curl -sL https://github.com/forattini-dev/vaulter/releases/latest/download/vaulter-linux -o vaulter
          chmod +x vaulter
          sudo mv vaulter /usr/local/bin/

      - name: Deploy
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          vaulter k8s:secret -e prd | kubectl apply -f -

GitHub Actions (Matrix Deploy)

name: Deploy All Environments
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, stg, prd]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy secrets
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          npx vaulter k8s:secret -e ${{ inputs.environment }} | kubectl apply -f -

      - name: Deploy configmaps
        run: |
          npx vaulter k8s:configmap -e ${{ inputs.environment }} | kubectl apply -f -

GitLab CI

stages:
  - deploy

deploy-secrets:
  stage: deploy
  image: node:22-alpine
  script:
    - npx vaulter k8s:secret -e ${CI_ENVIRONMENT_NAME} | kubectl apply -f -
  environment:
    name: $CI_COMMIT_REF_NAME
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        CI_ENVIRONMENT_NAME: prd
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        CI_ENVIRONMENT_NAME: dev

Jenkins Pipeline

pipeline {
    agent any

    environment {
        VAULTER_KEY = credentials('vaulter-key')
        AWS_ACCESS_KEY_ID = credentials('aws-access-key')
        AWS_SECRET_ACCESS_KEY = credentials('aws-secret-key')
    }

    stages {
        stage('Deploy Secrets') {
            steps {
                sh 'npx vaulter k8s:secret -e prd | kubectl apply -f -'
            }
        }
    }
}

Docker Integration

# Recommended: Use --env-file for production (handles all values safely)
vaulter export -e prd --format=env > .env.prd
docker run --env-file .env.prd myapp

# For simple values only: command substitution (no spaces/newlines in values)
docker run $(vaulter export -e prd --format=docker-args) myapp

Note: The docker-args format outputs -e "KEY=VALUE" flags. Due to shell word-splitting, values containing spaces or special characters won't work correctly with $(...) substitution. Use --env-file for complex values or production deployments.

For docker build with build args, use shell format:

# Export to shell and use in build
eval $(vaulter export -e prd)
docker build \
  --build-arg DATABASE_URL="$DATABASE_URL" \
  --build-arg API_KEY="$API_KEY" \
  -t myapp .

Terraform Integration

# Generate tfvars
vaulter tf:vars -e prd > secrets.auto.tfvars

# Or inline
terraform plan -var-file=<(vaulter tf:vars -e prd)

Helm Integration

# Upgrade with secrets as values
vaulter helm:values -e prd | helm upgrade myapp ./chart -f -

# Or save to file
vaulter helm:values -e prd > values.secrets.yaml
helm upgrade myapp ./chart -f values.yaml -f values.secrets.yaml

Shell Aliases (Development)

# Add to ~/.bashrc or ~/.zshrc
alias vdev='eval $(vaulter export -e dev)'
alias vstg='eval $(vaulter export -e stg)'
alias vprd='eval $(vaulter export -e prd)'

# Usage
vdev npm run dev
vstg npm run test:integration

Configuration

Basic Config

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

project: my-project
service: api  # optional, for monorepos

backend:
  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
    - file: .vaulter/.key
  # Secret rotation settings
  rotation:
    enabled: true
    interval_days: 90
    patterns:
      - "*_KEY"
      - "*_SECRET"
      - "*_TOKEN"

# Audit logging
audit:
  enabled: true
  retention_days: 90
  mask_values: true

environments:
  - dev
  - stg
  - prd

default_environment: dev

Directory Modes

Unified Mode (Default)

my-project/
├── .vaulter/
│   ├── config.yaml
│   └── environments/
│       ├── dev.env
│       ├── stg.env
│       └── prd.env

Split Mode

Separates configs (committable) from secrets (gitignored):

my-project/
├── .vaulter/config.yaml
└── deploy/
    ├── configs/           # ✅ Committable (PORT, HOST, LOG_LEVEL)
    │   ├── dev.env
    │   └── prd.env
    └── secrets/           # ❌ Gitignored (DATABASE_URL, API_KEY)
        ├── dev.env
        └── prd.env

directories:
  mode: split
  configs: deploy/configs
  secrets: deploy/secrets

Initialize with: vaulter init --split

Backend URLs

Integrations

Kubernetes

# Deploy Secret
vaulter k8s:secret -e prd -n my-namespace | kubectl apply -f -

# Deploy ConfigMap
vaulter k8s:configmap -e prd | kubectl apply -f -

Note: Custom secret/configmap names are configured in .vaulter/config.yaml:

integrations:
  kubernetes:
    secret_name: my-app-secrets
    configmap_name: my-app-config

Helm

# Pass as values
vaulter helm:values -e prd | helm upgrade myapp ./chart -f -

# Save to file
vaulter helm:values -e prd > values.secrets.yaml

Terraform

# Generate tfvars
vaulter tf:vars -e prd > terraform.tfvars

# Generate JSON
vaulter tf:json -e prd > terraform.tfvars.json

Monorepo Support

Vaulter auto-detects all major monorepo tools:

Scan Command

# Discover all packages
vaulter scan

# Output:
# Monorepo: NX
# Found 17 package(s):
#   ✓ Initialized: 3
#   ○ Not initialized: 14
#   📄 With .env files: 11

Batch Operations

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

# Sync specific services
vaulter sync -e dev -s api,worker

API Usage

import { VaulterClient, loadConfig } from 'vaulter'

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

await client.connect()

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

await client.disconnect()

Dotenv Compatible

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

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

MCP Server

Vaulter includes a Model Context Protocol (MCP) server for AI assistant integration.

Setup

# Start server
vaulter mcp

# Test with MCP Inspector
npx @anthropic-ai/mcp-inspector vaulter mcp

Claude Desktop Config

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

Available Tools (21)

Core Operations

Discovery & Analysis

Integrations

Key Management

Resources (8)

Prompts (5)

• setup_project — Initialize a new project
• migrate_dotenv — Migrate existing .env
• deploy_secrets — Deploy to Kubernetes
• compare_environments — Compare two environments
• security_audit — Audit for security issues

Pre-built Binaries

Download from Releases:

License

MIT © Forattini