vaulter 0.2.1 → 1.0.0

package/README.md

@@ -18,9 +18,11 @@ 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
+# Set secrets (encrypted, synced to backend)
+vaulter set DATABASE_URL="postgres://localhost/mydb" API_KEY="sk-secret-key" -e dev
+
+# Set configs (plain text in split mode, synced in unified mode)
+vaulter set PORT::3000 LOG_LEVEL::debug -e dev
 
 # Export to shell
 eval $(vaulter export -e dev)
@@ -50,13 +52,49 @@ MCP server for Claude AI. Zero config for dev, production-ready.
 
 ---
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [What's Inside](#whats-inside)
+- [Highlights](#highlights)
+- [Commands](#commands)
+- [Configuration](#configuration)
+  - [Directory Modes](#directory-modes)
+- [Backend URLs](#backend-urls)
+- [Encryption](#encryption)
+- [Running Commands](#running-commands)
+  - [Shell Scripts](#shell-scripts)
+  - [Interactive Tools](#interactive-tools)
+- [Integrations](#integrations)
+  - [kubectl](#kubectl)
+  - [Helm & Helmfile](#helm--helmfile)
+  - [Terraform & Terragrunt](#terraform--terragrunt)
+- [Monorepo Support](#monorepo-support)
+  - [NX Monorepo](#nx-monorepo)
+  - [Turborepo](#turborepo)
+- [MCP Server](#mcp-server)
+  - [MCP Tools](#mcp-tools-14)
+  - [MCP Resources](#mcp-resources-5)
+  - [MCP Prompts](#mcp-prompts-5)
+- [CI/CD](#cicd)
+  - [Developer Daily Workflow](#developer-daily-workflow)
+  - [GitHub Actions](#github-actions)
+  - [GitLab CI](#gitlab-ci)
+  - [CircleCI](#circleci)
+  - [Azure DevOps](#azure-devops)
+- [Security Best Practices](#security-best-practices)
+- [API Usage](#api-usage)
+- [Pre-built Binaries](#pre-built-binaries)
+
+---
+
 ## What's Inside
 
 | Category | Features |
 |:---------|:---------|
 | **Backends** | AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, FileSystem, Memory |
-| **Encryption** | AES-256-GCM via s3db.js, field-level encryption, key rotation |
-| **Environments** | dev, stg, prd, sbx, dr (fully customizable) |
+| **Encryption** | AES-256-GCM via s3db.js, field-level encryption |
+| **Environments** | dev, stg, prd, sbx, dr (configurable subset) |
 | **Integrations** | Kubernetes Secret/ConfigMap, Helm values.yaml, Terraform tfvars |
 | **Monorepo** | Service discovery, batch operations, config inheritance |
 | **MCP Server** | Claude AI integration via Model Context Protocol |
@@ -141,7 +179,8 @@ loader({ path: '.env.local', override: true })
 |:--------|:------------|:--------|
 | `init` | Initialize project | `vaulter init` |
 | `get <key>` | Get a variable | `vaulter get DATABASE_URL -e prd` |
-| `set <key> <value>` | Set a variable | `vaulter set API_KEY "sk-..." -e prd` |
+| `set KEY=val ...` | Set secrets (batch) | `vaulter set KEY1=v1 KEY2=v2 -e prd` |
+| `set KEY::val ...` | Set configs (plain) | `vaulter set PORT::3000 HOST::0.0.0.0 -e dev` |
 | `delete <key>` | Delete a variable | `vaulter delete OLD_KEY -e dev` |
 | `list` | List all variables | `vaulter list -e prd` |
 | `export` | Export for shell | `eval $(vaulter export -e dev)` |
@@ -172,6 +211,35 @@ loader({ path: '.env.local', override: true })
 | `services` | List monorepo services | `vaulter services` |
 | `mcp` | Start MCP server | `vaulter mcp` |
 
+### Set Command Syntax
+
+HTTPie-style separators for differentiating secrets from configs:
+
+```bash
+# 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 secret (number/boolean)
+
+# Configs (plain text, file only in split mode, synced in unified mode)
+vaulter set PORT::3000 HOST::localhost   # Configs
+
+# With metadata
+vaulter set DB_URL=postgres://... @tag:database,sensitive @owner:backend -e prd
+
+# Legacy syntax (still works)
+vaulter set KEY "value" -e dev           # Treated as secret
+```
+
+| Separator | Type | Backend Sync | Encryption (backend) |
+|:----------|:-----|:-------------|:-----------|
+| `=` | Secret | ✓ | ✓ |
+| `:=` | Secret (typed) | ✓ | ✓ |
+| `::` | Config | Split: ✗ / Unified: ✓ | ✓ |
+| `@key:value` | Metadata | — | — |
+
+Note: Config files remain plain text; backend storage is encrypted for all values.
+
 ## Global Options
 
 ```
@@ -227,7 +295,7 @@ Sync merges local and remote variables. Conflicts are resolved by `sync.conflict
 
 ```yaml
 sync:
-  conflict: local   # local | remote | prompt | error
+  conflict: local   # local | remote | error
   ignore:
     - "PUBLIC_*"
   required:
@@ -236,9 +304,70 @@ sync:
 ```
 
 Notes:
-- `prompt` and `error` will stop the sync if conflicts are detected.
+- `local` (default): Local values win on conflict, remote-only keys are pulled to local
+- `remote`: Remote values win on conflict
+- `error`: Stop sync if any conflicts are detected
 - When reading from stdin, sync only updates the backend (local file is not changed).
 
+### Directory Modes
+
+Vaulter supports two directory structures for organizing environment files:
+
+#### Unified Mode (Default)
+
+All environment files in a single directory:
+
+```
+my-project/
+├── .vaulter/
+│   ├── config.yaml
+│   └── environments/
+│       ├── dev.env        # All vars (secrets + configs)
+│       ├── stg.env
+│       └── prd.env
+```
+
+#### Split Mode
+
+Separate directories for configs (committable) and secrets (gitignored):
+
+```
+my-project/
+├── .vaulter/
+│   └── config.yaml
+└── deploy/
+    ├── configs/           # ✅ Committable (non-sensitive)
+    │   ├── dev.env        # NODE_ENV, PORT, LOG_LEVEL
+    │   ├── stg.env
+    │   └── prd.env
+    └── secrets/           # ❌ Gitignored (sensitive)
+        ├── dev.env        # DATABASE_URL, JWT_SECRET
+        ├── stg.env
+        └── prd.env
+```
+
+Configure split mode in `config.yaml`:
+
+```yaml
+directories:
+  mode: split              # "unified" (default) or "split"
+  configs: deploy/configs  # Non-sensitive vars (committable)
+  secrets: deploy/secrets  # Sensitive vars (gitignored)
+```
+
+Tip: scaffold split mode with `vaulter init --split`.
+
+**Behavior in split mode:**
+- `sync`, `pull`, `push` operate on the **secrets** directory
+- `k8s:secret` reads from local **secrets** file (no backend fetch)
+- `k8s:configmap` reads from local **configs** file (no backend fetch)
+- Configs are managed via git, secrets via vaulter
+
+**When to use split mode:**
+- Monorepos with deploy directories per service
+- Teams that want configs reviewed in PRs
+- Environments where non-sensitive configs should be in git
+
 ### Hooks
 
 ```yaml
@@ -322,6 +451,231 @@ security:
 
 `auto_encrypt.patterns` is used to classify secrets for integrations (K8s/Helm).
 
+## Running Commands
+
+Load environment variables into any command using `eval $(vaulter export)`.
+
+### Shell Scripts
+
+```bash
+# Run a script with environment variables
+eval $(vaulter export -e dev) ./myscript.sh
+
+# Or in two steps
+eval $(vaulter export -e dev)
+./myscript.sh
+
+# One-liner with subshell (vars don't persist after)
+(eval $(vaulter export -e prd) && ./deploy.sh)
+
+# Using env command (cleaner syntax)
+env $(vaulter export -e dev --format=shell) ./myscript.sh
+```
+
+### Interactive Tools
+
+```bash
+# k9s with production credentials
+eval $(vaulter export -e prd) k9s
+
+# psql with database URL
+eval $(vaulter export -e dev) psql $DATABASE_URL
+
+# redis-cli
+eval $(vaulter export -e dev) redis-cli -u $REDIS_URL
+
+# AWS CLI with credentials
+eval $(vaulter export -e prd) aws s3 ls
+
+# Docker run with env vars
+eval $(vaulter export -e dev) docker run --env-file <(vaulter export -e dev --format=env) myapp
+
+# Any Node.js app
+eval $(vaulter export -e dev) node server.js
+
+# Python app
+eval $(vaulter export -e dev) python app.py
+```
+
+### Shell Alias (Recommended)
+
+Add to your `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# Quick alias for common environments
+alias vdev='eval $(vaulter export -e dev)'
+alias vstg='eval $(vaulter export -e stg)'
+alias vprd='eval $(vaulter export -e prd)'
+
+# Usage
+vdev ./myscript.sh
+vprd k9s
+vstg psql $DATABASE_URL
+```
+
+### One-liner Pattern
+
+```bash
+# Pattern: eval $(vaulter export -e ENV) COMMAND
+eval $(vaulter export -e dev) npm run dev
+eval $(vaulter export -e prd) kubectl get pods
+eval $(vaulter export -e stg) terraform plan
+```
+
+## Integrations
+
+### kubectl
+
+```bash
+# Create Secret from vaulter
+vaulter k8s:secret -e prd | kubectl apply -f -
+
+# Create ConfigMap (non-secret vars)
+vaulter k8s:configmap -e prd | kubectl apply -f -
+
+# With custom name and namespace
+vaulter k8s:secret -e prd -n my-namespace --name my-app-secrets | kubectl apply -f -
+
+# Dry-run to see YAML
+vaulter k8s:secret -e prd --dry-run
+
+# Create secret from export (alternative)
+vaulter export -e prd --format=env | \
+  kubectl create secret generic myapp --from-env-file=/dev/stdin --dry-run=client -o yaml | \
+  kubectl apply -f -
+
+# Run kubectl with vaulter vars
+eval $(vaulter export -e prd) kubectl exec -it deploy/myapp -- env | grep DATABASE
+```
+
+### Helm & Helmfile
+
+#### Helm
+
+```bash
+# Generate values.yaml and pipe to helm
+vaulter helm:values -e prd | helm upgrade myapp ./chart -f -
+
+# Save values to file
+vaulter helm:values -e prd > values.prd.yaml
+helm upgrade myapp ./chart -f values.prd.yaml
+
+# With secrets separated (uses auto_encrypt.patterns)
+vaulter helm:values -e prd --secrets  # Only secret vars
+vaulter helm:values -e prd --config   # Only non-secret vars
+
+# Install with inline values
+helm install myapp ./chart \
+  --set-string DATABASE_URL="$(vaulter get DATABASE_URL -e prd)" \
+  --set-string API_KEY="$(vaulter get API_KEY -e prd)"
+```
+
+#### Helmfile
+
+```yaml
+# helmfile.yaml
+repositories:
+  - name: bitnami
+    url: https://charts.bitnami.com/bitnami
+
+releases:
+  - name: myapp
+    namespace: production
+    chart: ./charts/myapp
+    values:
+      - values.yaml
+      - values.prd.yaml  # Generated by: vaulter helm:values -e prd > values.prd.yaml
+```
+
+```bash
+# Generate values before helmfile sync
+vaulter helm:values -e prd > values.prd.yaml
+helmfile sync
+
+# Or use process substitution
+helmfile sync --values <(vaulter helm:values -e prd)
+
+# With environment variables for helmfile
+eval $(vaulter export -e prd) helmfile apply
+```
+
+### Terraform & Terragrunt
+
+#### Terraform
+
+```bash
+# Generate .tfvars file
+vaulter tf:vars -e prd > terraform.tfvars
+terraform plan
+
+# Generate JSON format
+vaulter tf:json -e prd > terraform.tfvars.json
+terraform plan -var-file=terraform.tfvars.json
+
+# Pass vars inline
+terraform plan \
+  -var="database_url=$(vaulter get DATABASE_URL -e prd)" \
+  -var="api_key=$(vaulter get API_KEY -e prd)"
+
+# Use TF_VAR_* environment variables
+eval $(vaulter export -e prd --format=tfvars)
+terraform plan
+
+# Pipe directly (requires bash process substitution)
+terraform plan -var-file=<(vaulter tf:vars -e prd)
+```
+
+#### Terragrunt
+
+```bash
+# Set env vars for terragrunt
+eval $(vaulter export -e prd) terragrunt plan
+
+# Generate inputs file
+vaulter tf:vars -e prd > inputs.tfvars
+terragrunt plan --terragrunt-config terragrunt.hcl
+
+# In terragrunt.hcl - use environment variables
+# terragrunt.hcl
+inputs = {
+  database_url = get_env("DATABASE_URL", "")
+  api_key      = get_env("API_KEY", "")
+}
+
+# Then run:
+eval $(vaulter export -e prd) terragrunt apply
+
+# Or with inputs file
+# terragrunt.hcl
+terraform {
+  extra_arguments "custom_vars" {
+    commands = get_terraform_commands_that_need_vars()
+    arguments = [
+      "-var-file=inputs.tfvars"
+    ]
+  }
+}
+```
+
+```bash
+# Full workflow with terragrunt
+vaulter pull -e prd                    # Get latest vars
+vaulter tf:vars -e prd > inputs.tfvars # Generate tfvars
+terragrunt plan                        # Plan with vars
+terragrunt apply                       # Apply
+```
+
+### Integration Summary
+
+| Tool | Command |
+|:-----|:--------|
+| **kubectl** | `vaulter k8s:secret -e prd \| kubectl apply -f -` |
+| **helm** | `vaulter helm:values -e prd \| helm upgrade app ./chart -f -` |
+| **helmfile** | `vaulter helm:values -e prd > values.prd.yaml && helmfile sync` |
+| **terraform** | `vaulter tf:vars -e prd > terraform.tfvars && terraform plan` |
+| **terragrunt** | `eval $(vaulter export -e prd) terragrunt apply` |
+| **any command** | `eval $(vaulter export -e ENV) COMMAND` |
+
 ## Monorepo Support
 
 Vaulter auto-discovers services with `.vaulter/` directories and supports config inheritance.
@@ -433,44 +787,508 @@ vaulter sync -e dev -s "svc-*"
 vaulter export -e prd --all --format=json
 ```
 
-## MCP Tools
+## MCP Server
+
+Vaulter includes a full-featured **Model Context Protocol (MCP)** server for AI assistant integration. Works with Claude, ChatGPT, and any MCP-compatible client.
+
+### Quick Setup
+
+```bash
+# Start MCP server
+vaulter mcp
+```
+
+Add to your Claude config (`~/.config/claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "vaulter": {
+      "command": "npx",
+      "args": ["vaulter", "mcp"]
+    }
+  }
+}
+```
+
+Or with the binary:
+
+```json
+{
+  "mcpServers": {
+    "vaulter": {
+      "command": "/usr/local/bin/vaulter",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### MCP Tools (14)
+
+The MCP server exposes 14 tools organized into categories:
+
+#### Core Tools
+
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_get` | Get a single variable | "Get the DATABASE_URL for production" |
+| `vaulter_set` | Set a variable with tags | "Set API_KEY to sk-xxx for dev" |
+| `vaulter_delete` | Delete a variable | "Remove the old LEGACY_KEY" |
+| `vaulter_list` | List all variables | "Show all vars in staging" |
+| `vaulter_export` | Export in various formats | "Export prod vars as JSON" |
+
+#### Sync Tools
+
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_sync` | Bidirectional sync | "Sync local .env with dev backend" |
+| `vaulter_pull` | Download from backend | "Pull production vars to .env.prd" |
+| `vaulter_push` | Upload to backend | "Push .env.local to dev" |
+
+#### Analysis Tools
 
-| Tool | Description |
-|:-----|:------------|
-| `vaulter_get` | Get a single variable |
-| `vaulter_set` | Set a variable |
-| `vaulter_delete` | Delete a variable |
-| `vaulter_list` | List all variables |
-| `vaulter_export` | Export in various formats |
-| `vaulter_sync` | Sync with .env file |
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_compare` | Compare two environments | "What's different between stg and prd?" |
+| `vaulter_search` | Search by key pattern | "Find all vars containing DATABASE" |
+
+#### Monorepo Tools
+
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_services` | List discovered services | "What services are in this monorepo?" |
+
+#### Kubernetes Tools
+
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_k8s_secret` | Generate K8s Secret YAML | "Generate a K8s secret for prod" |
+| `vaulter_k8s_configmap` | Generate K8s ConfigMap | "Create a ConfigMap for non-secrets" |
+
+#### Setup Tools
+
+| Tool | Description | Example Use |
+|:-----|:------------|:------------|
+| `vaulter_init` | Initialize new project | "Set up vaulter in this project" |
+
+### MCP Resources (5)
+
+Resources provide read-only views of your secrets and configuration:
+
+| Resource URI | Description | Content |
+|:-------------|:------------|:--------|
+| `vaulter://config` | Project configuration | YAML from .vaulter/config.yaml |
+| `vaulter://services` | Monorepo services | JSON list of discovered services |
+| `vaulter://project/env` | Environment variables | .env format for project/env |
+| `vaulter://project/env/service` | Service-specific vars | .env format for service |
+| `vaulter://compare/env1/env2` | Environment comparison | Diff between two environments |
+
+**Example resource access:**
+- `vaulter://config` → Current config.yaml content
+- `vaulter://my-app/prd` → Production vars for my-app
+- `vaulter://compare/dev/prd` → What's different between dev and prod
+
+### MCP Prompts (5)
+
+Pre-configured workflow prompts guide AI through complex operations:
+
+| Prompt | Description | Arguments |
+|:-------|:------------|:----------|
+| `setup_project` | Initialize a new vaulter project | `project_name`, `mode?`, `backend?` |
+| `migrate_dotenv` | Migrate existing .env to vaulter | `file_path`, `environment`, `dry_run?` |
+| `deploy_secrets` | Deploy secrets to Kubernetes | `environment`, `namespace?`, `secret_name?` |
+| `compare_environments` | Compare two environments | `source_env`, `target_env`, `show_values?` |
+| `security_audit` | Audit secrets for security issues | `environment`, `strict?` |
+
+**Example prompt usage in Claude:**
+- "Use the setup_project prompt to create a new project called api-service"
+- "Run the migrate_dotenv prompt for .env.local to dev environment"
+- "Execute security_audit for production in strict mode"
+
+### MCP Capabilities Summary
+
+| Category | Count | Features |
+|:---------|------:|:---------|
+| **Tools** | 14 | CRUD, sync, compare, K8s, init |
+| **Resources** | 5 | Config, services, vars, comparison |
+| **Prompts** | 5 | Setup, migrate, deploy, compare, audit |
+| **Formats** | 5 | shell, json, yaml, env, tfvars |
+
+### Example AI Conversations
+
+**Setting up a new project:**
+> "Help me set up vaulter for my new api-service project using S3 backend"
+
+The AI will use `vaulter_init`, guide through backend config, and set up encryption.
+
+**Migrating from dotenv:**
+> "I have a .env.production file with 50 variables. Help me migrate to vaulter"
+
+The AI will analyze the file, identify secrets vs configs, and sync to backend.
+
+**Deploying to Kubernetes:**
+> "Generate Kubernetes secrets for production and show me how to deploy them"
+
+The AI will use `vaulter_k8s_secret` and provide kubectl commands.
+
+**Comparing environments:**
+> "What variables are in staging but missing from production?"
+
+The AI will use `vaulter_compare` and show the differences.
+
+**Security review:**
+> "Audit my production secrets for security issues"
+
+The AI will analyze variable patterns, check for weak values, and provide recommendations.
 
 ## CI/CD
 
+### Developer Daily Workflow
+
+A typical day with vaulter:
+
+#### 1. Morning Setup
+
+```bash
+# Pull latest secrets to your local .env
+vaulter pull -e dev
+
+# Start development with loaded vars
+eval $(vaulter export -e dev) npm run dev
+
+# Or use the alias (add to ~/.bashrc)
+alias vdev='eval $(vaulter export -e dev)'
+vdev npm run dev
+```
+
+#### 2. Adding New Variables
+
+```bash
+# Add a new secret (encrypted, synced to backend)
+vaulter set NEW_API_KEY="sk-xxx" -e dev
+
+# Add a config (plain text)
+vaulter set LOG_LEVEL::debug -e dev
+
+# Batch add multiple vars
+vaulter set DB_HOST::localhost DB_PORT::5432 DB_PASSWORD="secret123" -e dev
+
+# Check what you have
+vaulter list -e dev
+```
+
+#### 3. Syncing with Team
+
+```bash
+# Your teammate added new vars - pull them
+vaulter pull -e dev
+
+# You made changes - push to backend
+vaulter push -e dev
+
+# Two-way sync (recommended)
+vaulter sync -e dev
+
+# Preview before sync
+vaulter sync -e dev --dry-run
+```
+
+#### 4. Testing Different Environments
+
+```bash
+# Run with staging config
+eval $(vaulter export -e stg) npm test
+
+# Compare what's different in production
+vaulter compare -e dev -e prd
+
+# One-liner to check production
+vdev npm run dev   # dev
+vstg npm test      # stg
+vprd npm run build # prd (be careful!)
+```
+
+#### 5. Before Code Review
+
+```bash
+# Make sure all required vars are documented
+vaulter list -e dev --json | jq 'keys'
+
+# Check nothing sensitive is in wrong place
+vaulter search "*PASSWORD*" -e dev
+vaulter search "*SECRET*" -e dev
+```
+
+#### 6. Deployment Prep
+
+```bash
+# Generate K8s secret and review
+vaulter k8s:secret -e prd --dry-run
+
+# Generate and apply
+vaulter k8s:secret -e prd | kubectl apply -f -
+
+# Or export for Helm
+vaulter helm:values -e prd > values.prd.yaml
+helm upgrade myapp ./chart -f values.prd.yaml
+```
+
+### Shell Aliases (Recommended)
+
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# Quick environment loading
+alias vdev='eval $(vaulter export -e dev)'
+alias vstg='eval $(vaulter export -e stg)'
+alias vprd='eval $(vaulter export -e prd)'
+
+# Common operations
+alias vpull='vaulter pull -e dev'
+alias vpush='vaulter push -e dev'
+alias vsync='vaulter sync -e dev'
+alias vlist='vaulter list -e dev'
+
+# K8s shortcuts
+alias vk8s='vaulter k8s:secret'
+alias vhelm='vaulter helm:values'
+
+# Usage
+vdev npm run dev              # Dev with env vars
+vstg npm test                 # Test with staging
+vpull && vdev npm run dev     # Pull latest, then run
+vk8s -e prd | kubectl apply -f -  # Deploy secrets
+```
+
 ### GitHub Actions
 
+#### Basic Deploy Secrets
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy secrets to K8s
+        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 -
+```
+
+#### Multi-Environment Deploy
+
 ```yaml
+name: Deploy to Environment
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to deploy'
+        required: true
+        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 }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         run: |
+          npx vaulter k8s:secret -e ${{ inputs.environment }} | kubectl apply -f -
+          npx vaulter k8s:configmap -e ${{ inputs.environment }} | kubectl apply -f -
+```
+
+#### Monorepo with Matrix
+
+```yaml
+name: Deploy Services
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service: [api, web, worker]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy ${{ matrix.service }} secrets
+        env:
+          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
+        run: |
+          cd apps/${{ matrix.service }}
           npx vaulter k8s:secret -e prd | kubectl apply -f -
 ```
 
+#### PR Preview Environment
+
+```yaml
+name: PR Preview
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create preview secrets
+        env:
+          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
+        run: |
+          # Use dev secrets for PR previews
+          npx vaulter k8s:secret -e dev -n preview-pr-${{ github.event.number }} | \
+            kubectl apply -f -
+```
+
+#### Validate Secrets Exist
+
+```yaml
+name: Validate Secrets
+on:
+  pull_request:
+    paths:
+      - '.vaulter/**'
+      - 'deploy/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check required secrets exist
+        env:
+          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
+        run: |
+          # List and verify required secrets are set
+          npx vaulter list -e prd --json | jq -e '.DATABASE_URL and .API_KEY'
+```
+
 ### GitLab CI
 
 ```yaml
-deploy:
+stages:
+  - validate
+  - deploy
+
+variables:
+  VAULTER_KEY: $VAULTER_KEY
+
+validate-secrets:
+  stage: validate
+  script:
+    - npx vaulter list -e $CI_ENVIRONMENT_NAME --json | jq -e 'keys | length > 0'
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+
+deploy-secrets:
+  stage: deploy
   script:
     - npx vaulter k8s:secret -e prd | kubectl apply -f -
-  variables:
-    VAULTER_KEY: $VAULTER_KEY
+  environment:
+    name: production
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+```
+
+### CircleCI
+
+```yaml
+version: 2.1
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run:
+          name: Deploy secrets
+          command: |
+            npx vaulter k8s:secret -e prd | kubectl apply -f -
+          environment:
+            VAULTER_KEY: ${VAULTER_KEY}
+
+workflows:
+  deploy:
+    jobs:
+      - deploy:
+          filters:
+            branches:
+              only: main
+```
+
+### Azure DevOps
+
+```yaml
+trigger:
+  - main
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '20.x'
+
+  - script: |
+      npx vaulter k8s:secret -e prd | kubectl apply -f -
+    displayName: 'Deploy secrets'
+    env:
+      VAULTER_KEY: $(VAULTER_KEY)
+      AWS_ACCESS_KEY_ID: $(AWS_ACCESS_KEY_ID)
+      AWS_SECRET_ACCESS_KEY: $(AWS_SECRET_ACCESS_KEY)
+```
+
+### CI/CD Best Practices
+
+| Practice | Recommendation |
+|:---------|:---------------|
+| **Store VAULTER_KEY securely** | Use CI provider's secret management |
+| **Use IAM roles when possible** | Prefer roles over hardcoded credentials |
+| **Different keys per environment** | Don't share prd key with dev |
+| **Validate before deploy** | Run `--dry-run` first in pipelines |
+| **Use environment protection** | Require approval for prd deploys |
+| **Cache vaulter binary** | Download once per pipeline, not per job |
+
+### Caching Vaulter Binary
+
+```yaml
+# GitHub Actions
+- uses: actions/cache@v3
+  with:
+    path: ~/.npm
+    key: vaulter-${{ runner.os }}
+
+# Or download binary directly
+- name: Install vaulter
+  run: |
+    curl -sL https://github.com/forattini-dev/vaulter/releases/latest/download/vaulter-linux -o /usr/local/bin/vaulter
+    chmod +x /usr/local/bin/vaulter
 ```
 
 ## Security Best Practices
@@ -490,6 +1308,7 @@ deploy:
 .vaulter/.key
 .vaulter/config.local.yaml
 **/config.local.yaml
+deploy/secrets/
 .env
 .env.*
 ```
@@ -546,7 +1365,9 @@ await client.disconnect()
 | Backends | 7 (S3, MinIO, R2, Spaces, B2, FileSystem, Memory) |
 | Environments | 5 (dev, stg, prd, sbx, dr) |
 | Export Formats | 5 (shell, json, yaml, env, tfvars) |
-| MCP Tools | 6 |
+| MCP Tools | 14 (core, sync, analysis, monorepo, k8s, setup) |
+| MCP Resources | 5 (config, services, vars, service vars, compare) |
+| MCP Prompts | 5 (setup, migrate, deploy, compare, audit) |
 | Integrations | 5 (K8s Secret, K8s ConfigMap, Helm, Terraform, tfvars) |
 
 ## Pre-built Binaries