vaultenv

Local-first, encrypted ENV manager for developers

Store, organize, and retrieve your API keys, private keys, RPC URLs, and secrets — encrypted at rest, never synced to the cloud, and accessible directly from your terminal or Claude Code via MCP.

Features

• AES-256-GCM encryption with PBKDF2 key derivation (100,000 iterations)
• Project-based organization — group keys by project
• One-command clipboard copy — vaultenv get myproject MY_KEY
• Shell ENV injection — eval "$(vaultenv load myproject)"
• Run commands with ENVs — vaultenv run myproject -- npm run dev
• MCP server — let Claude Code fetch your secrets directly
• Bags.fm integration — store API keys, query fee-share stats, pools, and token feed
• 100% offline — zero network calls, zero telemetry
• Works on macOS, Linux, Windows

Installation

npm install -g @codeswithroh/vaultenv

Quick Start

# First run — creates vault with master password
vaultenv add myproject ALCHEMY_RPC_URL https://eth-mainnet...

# Unlock after a new terminal session
vaultenv unlock

# Add more keys
vaultenv add myproject PRIVATE_KEY -c "Deployer wallet — never commit"
vaultenv add myproject API_TOKEN sk_live_xxx --expires 2026-12-01

# Copy to clipboard
vaultenv get myproject PRIVATE_KEY

# Inject into current shell session
eval "$(vaultenv load myproject)"
echo $PRIVATE_KEY

# Run a command with ENVs injected (one-shot, doesn't pollute shell)
vaultenv run myproject -- npx hardhat deploy

# Export as .env file
vaultenv export myproject > .env

All Commands

Vault Management

| Command | Description | |---|---| | vaultenv init | First-time setup (auto-triggered on first use) | | vaultenv unlock | Unlock vault with master password (15 min session) | | vaultenv lock | Lock vault immediately (clears session) |

Adding & Editing Keys

| Command | Description | |---|---| | vaultenv add <project> <key> [value] | Add a key (prompts for value if omitted) | | vaultenv add <project> <key> -c "comment" | Add a key with a comment | | vaultenv add <project> <key> --expires 2026-12-01 | Add a key with expiration date | | vaultenv update <project> <key> [value] | Update an existing key's value |

Reading Keys

| Command | Description | |---|---| | vaultenv get <project> <key> | Copy value to clipboard | | vaultenv show <project> <key> | Print masked value to stdout | | vaultenv show <project> <key> --reveal | Print plaintext value to stdout | | vaultenv list <project> | List all keys (masked, with comments) | | vaultenv list <project> --expired | List only expired keys | | vaultenv projects | List all project names |

Shell Integration

| Command | Description | |---|---| | eval "$(vaultenv load <project>)" | Inject ENVs into current shell session | | eval "$(vaultenv unload <project>)" | Remove ENVs from current shell session | | vaultenv run <project> -- <command> | Run command with ENVs injected (single invocation) |

Import & Export

| Command | Description | |---|---| | vaultenv import <project> <file> | Import a .env file into a project | | vaultenv import <project> <url> | Import a .env file from a URL | | vaultenv export <project> | Print .env file to stdout | | vaultenv export <project> > .env | Write .env file to disk | | vaultenv export <project> --format json | Export as JSON |

Project Management

| Command | Description | |---|---| | vaultenv delete <project> <key> | Delete a specific key | | vaultenv remove <project> | Delete an entire project | | vaultenv rename <project> <newname> | Rename a project |

MCP Server

| Command | Description | |---|---| | vaultenv mcp | Start the MCP server (vault must be unlocked) |

Shell Completions

# Bash
source <(vaultenv completions bash)
# Or add to ~/.bashrc:
echo 'source <(vaultenv completions bash)' >> ~/.bashrc

# Zsh
source <(vaultenv completions zsh)
# Or add to ~/.zshrc:
echo 'source <(vaultenv completions zsh)' >> ~/.zshrc

Important: The completions script also installs a shell function that makes vaultenv load and vaultenv unload work correctly (they need to run in the current shell context via eval).

MCP Integration with Claude Code

Add vaultenv to your Claude Code MCP config (~/.claude/claude_desktop_config.json or ~/.claude.json):

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

Then unlock your vault and start the MCP server:

vaultenv unlock
# Claude Code will run `vaultenv mcp` automatically when needed

MCP Tools Available to Claude

| Tool | Description | |---|---| | vaultenv_get_key | Get a specific key value | | vaultenv_list_keys | List all keys in a project | | vaultenv_list_projects | List all project names | | vaultenv_export_project | Get all key-value pairs for a project | | vaultenv_run_command | Run a command with ENVs injected |

Example: Tell Claude Code: "Use the Alchemy mainnet RPC from my vaultenv project 'web3-main'" — Claude will call vaultenv_get_key automatically.

Security

• Encryption: AES-256-GCM (authenticated encryption)
• Key derivation: PBKDF2, SHA-256, 100,000 iterations, random 32-byte salt per write
• Master password: Never stored on disk
• Vault file: ~/.vaultenv/vault.enc (permissions: 600)
• Config directory: ~/.vaultenv/ (permissions: 700)
• Session: Stored in ~/.vaultenv/.session (permissions: 600), expires after 15 minutes
• MCP server: Reads-only in v1; no writes via AI agents
• Network: Zero — 100% offline

Data Model

The vault file decrypts to this JSON structure:

{
  "version": 1,
  "projects": {
    "web3-main": {
      "ALCHEMY_RPC_URL": {
        "value": "https://eth-mainnet.g.alchemy.com/v2/xxx",
        "comment": "Mainnet endpoint - Alchemy dashboard",
        "expires": null
      },
      "PRIVATE_KEY": {
        "value": "0xabc123...",
        "comment": "Deployer wallet",
        "expires": "2026-12-01"
      }
    }
  }
}

Tech Stack

| Layer | Technology | |---|---| | Runtime | Node.js 18+ | | Language | TypeScript | | CLI | Commander.js | | Encryption | Node.js built-in crypto (AES-256-GCM, PBKDF2) | | Clipboard | clipboardy | | Prompts | @inquirer/prompts | | MCP | @modelcontextprotocol/sdk | | Build | tsup |

Bags.fm Integration

vaultenv has a native Bags.fm integration — the perfect fit for Solana developers. Store your Bags API key securely in the vault, then use it to query fee-share stats, active pools, token feeds, and swap quotes — all from the terminal (or via Claude Code's MCP tools).

Setup

# Get your API key at https://dev.bags.fm
vaultenv bags setup

Bags Commands

| Command | Description | |---|---| | vaultenv bags setup | Save Bags API key + wallet into vault | | vaultenv bags stats | Show your fee-share partner statistics | | vaultenv bags wallet twitter <handle> | Look up Solana wallet by social handle | | vaultenv bags pools | List active Bags.fm liquidity pools | | vaultenv bags pools --mint <address> | Get pool info for a specific token | | vaultenv bags quote <in> <out> <amount> | Get a swap quote | | vaultenv bags feed | Show recent token launches | | vaultenv bags fees | Show total lifetime fees on Bags.fm |

Bags MCP Tools (for Claude Code)

When running vaultenv mcp, Claude Code also gets access to these Bags tools:

| Tool | Description | |---|---| | bags_get_stats | Fetch partner fee-share stats | | bags_lookup_wallet | Look up wallet by social handle | | bags_get_feed | Get recent token launches | | bags_get_quote | Get a swap quote for a token pair |

Example: Tell Claude Code: "Check my Bags.fm fee-share stats" — it will call bags_get_stats using the API key stored securely in your vault.

Why vaultenv + Bags?

Solana developers using Bags.fm need to manage multiple credentials:

• BAGS_API_KEY — Bags developer API key
• SOLANA_PRIVATE_KEY — deployer wallet
• ALCHEMY_RPC_URL / HELIUS_RPC_URL — RPC endpoints

vaultenv stores all of these encrypted locally, and via MCP, Claude Code can fetch any of them on demand — no copy-paste, no plaintext files, no cloud exposure.

License

MIT