dev-vault 0.1.2

Developer secret vault + OIDC token provider — for developers, scripts, and AI agents

dev-vault

All your secrets in one command. Developer secret vault + OIDC token provider for developers, scripts, and AI agents.

Why dev-vault?

AI agents need secrets (API keys, bearer tokens) but can't safely read .env files, and hardcoding secrets in prompts is a security risk. dev-vault stores secrets in your OS keyring and exposes them via a simple CLI -- the secret never appears in conversation context, only where it's needed.

Quick Start

pip install dev-vault

Store a secret

dv set datadog api_key           # prompts for value (masked)
dv set datadog api_key "abc123"  # inline (for scripts)
dv set datadog app_key "def456"  # multiple fields per item

Retrieve a secret

dv get datadog                   # primary field -> stdout
dv get datadog api_key           # specific field (planned: prefix matching)
dv get default datadog api_key   # explicit vault

Use with AI agents

# Agent prompt: "use dv to get the bearer for the endpoint /api/motorcycles"
curl -H "Authorization: Bearer $(dv get prod caetano)" https://api.mottu.com/api/motorcycles

# Agent prompt: "query datadog for error rates"
DD_API_KEY=$(dv get datadog) python check_errors.py

# Or with dv run -- agent just says "run the script"
dv run -- python check_errors.py   # secrets injected from .dv.yaml

Run commands with secrets injected

# Explicit mapping
dv run -s DD_API_KEY=datadog/api_key -s DD_APP_KEY=datadog/app_key -- python app.py

# Using .dv.yaml manifest (checked into git, no secrets)
dv run -- python app.py

Project manifest (.dv.yaml)

Place in your project root. Maps environment variables to secret references:

secrets:
  DD_API_KEY: datadog/api_key
  DD_APP_KEY: datadog/app_key
  BEARER_TOKEN: prod/[e-mail]   # OIDC -> fresh token

Template injection

echo 'KEY={{dv://default/datadog/api_key}}' | dv inject
# Output: KEY=abc123

OIDC Token Provider

dev-vault can fetch fresh OIDC tokens from Keycloak (with more providers planned):

dv setup                         # interactive wizard
dv get prod [e-mail]    # returns a fresh access_token
dv get prod api-client           # client_credentials flow

Migrating from sso-cli

pip install dev-vault
dv migrate sso-cli               # imports config + keyring secrets
dv get prod [e-mail]    # same token, new tool

Commands

Command	Description
dv get [vault] <item> [field]	Retrieve secret or OIDC token
dv set [vault] <item> <field> [value]	Store a secret
dv run [-s KEY=ref] -- <cmd>	Run command with secrets as env vars
dv inject	Replace {{dv://...}} refs in stdin
dv item list|create|show|delete	Manage items
dv vault list|create|delete	Manage vaults
dv setup [--reset]	Interactive setup wizard
dv migrate sso-cli	Import from sso-cli
dv config show	Display current config

All commands support --json for programmatic output and -v for debug logging.

Security

dev-vault is built with a strict security-first approach:

• Secrets never touch disk. All secret values are stored exclusively in the OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). The config YAML only contains metadata (vault names, item names, field names, OIDC provider URLs).
• No secrets in logs or output. Debug/verbose mode (-v) never logs secret values. Human-friendly output goes to stderr; only raw secret values go to stdout (for $(dv get ...) substitution).
• Masked input. Interactive secret entry uses getpass (no terminal echo).
• Subprocess isolation. dv run injects secrets as environment variables only into the child process -- they don't leak into the parent shell or shell history.
• No network calls for static secrets. Only OIDC items make network requests, and only to the configured SSO endpoint.
• Config file permissions. The config directory (~/.config/dev-vault/) inherits your user's default umask. No world-readable files.
• No telemetry. dev-vault makes zero calls home. No analytics, no crash reporting.

Supply chain

• Minimal dependencies: httpx, pyyaml, keyring, rich, inquirer, pyperclip -- all well-established, actively maintained packages.
• Published to PyPI with standard setuptools build.
• Source available on GitHub for audit.

How It Works

• Config location: ~/.config/dev-vault/config.yaml (XDG-compliant), fallback ~/.dv.yaml. Override with DV_CONFIG env var.
• OIDC items fetch fresh tokens on every call (no caching, no stale tokens). Static items return stored keyring values.
• Secret references use dv://vault/item/field URIs or shorthand (item/field, vault/item).

---

PyPI package: https://pypi.org/project/dev-vault/

See Also

• Agent State -- Persistent memory and tools for AI agents
• sso-cli -- Single Sign-On token CLI (the ancestor of dev-vault)
• terminal-to-here -- VS Code extension to open terminal at any folder