dev-vault 0.1.2__tar.gz

dev_vault-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 caetanominuzzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dev_vault-0.1.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: dev-vault
+Version: 0.1.2
+Summary: Developer secret vault + OIDC token provider — for developers, scripts, and AI agents
+Author: Caetano Minuzzo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/caetanominuzzo/dev-vault
+Project-URL: Repository, https://github.com/caetanominuzzo/dev-vault
+Project-URL: Issues, https://github.com/caetanominuzzo/dev-vault/issues
+Project-URL: Changelog, https://github.com/caetanominuzzo/dev-vault/releases
+Keywords: vault,secrets,keyring,cli,oidc,keycloak,token,oauth,ai-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: rich>=13.0.0
+Requires-Dist: inquirer>=3.0.0
+Requires-Dist: keyring>=24.0.0
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install dev-vault
+```
+
+### Store a secret
+
+```bash
+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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```yaml
+secrets:
+  DD_API_KEY: datadog/api_key
+  DD_APP_KEY: datadog/app_key
+  BEARER_TOKEN: prod/admin@example.com   # OIDC -> fresh token
+```
+
+### Template injection
+
+```bash
+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):
+
+```bash
+dv setup                         # interactive wizard
+dv get prod admin@example.com    # returns a fresh access_token
+dv get prod api-client           # client_credentials flow
+```
+
+### Migrating from sso-cli
+
+```bash
+pip install dev-vault
+dv migrate sso-cli               # imports config + keyring secrets
+dv get prod admin@example.com    # 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](https://agentstate.tech/) -- Persistent memory and tools for AI agents
+- [sso-cli](https://pypi.org/project/sso-cli/) -- Single Sign-On token CLI (the ancestor of dev-vault)
+- [terminal-to-here](https://github.com/caetanominuzzo/terminal-to-here) -- VS Code extension to open terminal at any folder

dev_vault-0.1.2/README.md

@@ -0,0 +1,138 @@
+# 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
+
+```bash
+pip install dev-vault
+```
+
+### Store a secret
+
+```bash
+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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```yaml
+secrets:
+  DD_API_KEY: datadog/api_key
+  DD_APP_KEY: datadog/app_key
+  BEARER_TOKEN: prod/admin@example.com   # OIDC -> fresh token
+```
+
+### Template injection
+
+```bash
+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):
+
+```bash
+dv setup                         # interactive wizard
+dv get prod admin@example.com    # returns a fresh access_token
+dv get prod api-client           # client_credentials flow
+```
+
+### Migrating from sso-cli
+
+```bash
+pip install dev-vault
+dv migrate sso-cli               # imports config + keyring secrets
+dv get prod admin@example.com    # 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](https://agentstate.tech/) -- Persistent memory and tools for AI agents
+- [sso-cli](https://pypi.org/project/sso-cli/) -- Single Sign-On token CLI (the ancestor of dev-vault)
+- [terminal-to-here](https://github.com/caetanominuzzo/terminal-to-here) -- VS Code extension to open terminal at any folder

dev_vault-0.1.2/dev_vault/__init__.py

@@ -0,0 +1,3 @@
+"""dev-vault -- Developer secret vault + OIDC token provider."""
+
+__version__ = "0.1.0"

dev_vault-0.1.2/dev_vault/cli.py

@@ -0,0 +1,177 @@
+"""
+dev-vault CLI entry point.
+
+Routes subcommands to their respective handlers.
+"""
+
+import argparse
+import logging
+import os
+import sys
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+from . import __version__
+
+console = Console()
+logger = logging.getLogger("dev_vault")
+
+
+def _setup_logging(verbose: bool) -> None:
+    enabled = verbose or os.environ.get("DV_DEBUG", "").strip() in ("1", "true", "yes")
+    if not enabled:
+        return
+    logging.basicConfig(
+        level=logging.DEBUG,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler(
+            console=Console(stderr=True),
+            rich_tracebacks=True,
+            show_path=False,
+        )],
+    )
+    logger.debug("Verbose mode enabled")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dv",
+        description="dev-vault -- Developer secret vault + OIDC token provider",
+    )
+    parser.add_argument("--version", action="version", version=f"dev-vault {__version__}")
+    parser.add_argument("-v", "--verbose", action="store_true", help="enable debug output")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # dv get -- supports both:
+    #   dv get prod caetano           (positional: vault item)
+    #   dv get prod caetano password  (positional: vault item field)
+    #   dv get caetano                (just item, default vault)
+    #   dv get prod/caetano           (slash shorthand still works)
+    p_get = sub.add_parser("get", help="retrieve a secret or OIDC token")
+    p_get.add_argument("args", nargs="+", help="[vault] item [field] or vault/item[/field]")
+
+    # dv set -- supports:
+    #   dv set item field [value]
+    #   dv set vault item field [value]
+    p_set = sub.add_parser("set", help="store a secret")
+    p_set.add_argument("args", nargs="+", help="[vault] item field [value]")
+
+    # dv run
+    p_run = sub.add_parser("run", help="run command with secrets injected as env vars")
+    p_run.add_argument("-s", "--secret", action="append", help="KEY=ref mapping")
+    p_run.add_argument("run_command", nargs=argparse.REMAINDER, help="command to run (after --)")
+
+    # dv inject
+    sub.add_parser("inject", help="replace {{dv://...}} refs in stdin")
+
+    # dv item
+    p_item = sub.add_parser("item", help="manage items")
+    item_sub = p_item.add_subparsers(dest="item_action")
+
+    item_sub.add_parser("list", help="list items")
+    p_ic = item_sub.add_parser("create", help="create item")
+    p_ic.add_argument("name", help="item name")
+    p_ic.add_argument("--kind", choices=["static", "oidc"], default="static")
+    p_ic.add_argument("--vault", help="override vault")
+
+    p_is = item_sub.add_parser("show", help="show item details")
+    p_is.add_argument("name", help="item name")
+    p_is.add_argument("--vault", help="override vault")
+
+    p_id = item_sub.add_parser("delete", help="delete item")
+    p_id.add_argument("name", help="item name")
+    p_id.add_argument("--vault", help="override vault")
+
+    # dv vault
+    p_vault = sub.add_parser("vault", help="manage vaults")
+    vault_sub = p_vault.add_subparsers(dest="vault_action")
+    vault_sub.add_parser("list", help="list vaults")
+    vc = vault_sub.add_parser("create", help="create vault")
+    vc.add_argument("name", help="vault name")
+    vd = vault_sub.add_parser("delete", help="delete vault")
+    vd.add_argument("name", help="vault name")
+
+    # dv setup
+    p_setup = sub.add_parser("setup", help="interactive setup wizard")
+    p_setup.add_argument("--reset", action="store_true", help="backup config and start fresh")
+
+    # dv migrate
+    p_migrate = sub.add_parser("migrate", help="import from another tool")
+    p_migrate.add_argument("source", nargs="?", default="sso-cli", help="source tool (default: sso-cli)")
+
+    # dv config
+    p_config = sub.add_parser("config", help="show configuration")
+    config_sub = p_config.add_subparsers(dest="config_action")
+    config_sub.add_parser("show", help="display current config")
+
+    return parser
+
+
+def cli() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    _setup_logging(args.verbose)
+
+    # Strip leading '--' from run command
+    if args.command == "run" and hasattr(args, "run_command"):
+        cmd = getattr(args, "run_command", [])
+        if cmd and cmd[0] == "--":
+            args.run_command = cmd[1:]
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    # Propagate --json to args
+    try:
+        _dispatch(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        sys.exit(130)
+    except Exception as e:
+        logger.debug("Error: %s", e, exc_info=True)
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _dispatch(args) -> None:
+    cmd = args.command
+    if cmd == "get":
+        from .commands.get import run
+        run(args)
+    elif cmd == "set":
+        from .commands.set_cmd import run
+        run(args)
+    elif cmd == "run":
+        from .commands.run import run as run_cmd
+        run_cmd(args)
+    elif cmd == "inject":
+        from .commands.inject import run
+        run(args)
+    elif cmd == "item":
+        from .commands.item import run
+        run(args)
+    elif cmd == "vault":
+        from .commands.vault import run
+        run(args)
+    elif cmd == "setup":
+        from .commands.setup import run
+        run(args)
+    elif cmd == "migrate":
+        from .commands.migrate import run
+        run(args)
+    elif cmd == "config":
+        from .commands.config_cmd import run
+        run(args)
+    else:
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

dev_vault-0.1.2/dev_vault/commands/config_cmd.py

@@ -0,0 +1,42 @@
+"""
+dv config show -- display current configuration.
+
+Usage:
+  dv config show
+"""
+
+import json as json_mod
+import logging
+import sys
+
+import yaml
+
+from ..core.config import find_config_path, load_config
+
+logger = logging.getLogger(__name__)
+
+
+def run(args) -> None:
+    """Execute the config command."""
+    action = getattr(args, "config_action", "show")
+    if action == "show":
+        _show(args)
+    else:
+        print(f"Unknown config action: {action}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _show(args) -> None:
+    config_path = find_config_path()
+    try:
+        config = load_config()
+    except FileNotFoundError:
+        print(f"No config found at: {config_path}", file=sys.stderr)
+        sys.exit(1)
+
+    if getattr(args, "json", False):
+        print(json_mod.dumps({"path": config_path, "config": config}, indent=2))
+        return
+
+    print(f"Config: {config_path}\n")
+    print(yaml.dump(config, default_flow_style=False, sort_keys=False), end="")

dev_vault-0.1.2/dev_vault/commands/get.py

@@ -0,0 +1,134 @@
+"""
+dv get -- retrieve a secret or OIDC token.
+
+Usage:
+  dv get <item>                    # default vault, primary field
+  dv get <vault> <item>            # specific vault
+  dv get <vault> <item> <field>    # specific vault + field
+  dv get vault/item/field          # slash shorthand
+"""
+
+import asyncio
+import json as json_mod
+import logging
+import sys
+
+from ..core.config import ensure_config, get_item, get_default_vault, list_all_items
+from ..core.keyring_store import get_secret
+from ..core.resolver import resolve, resolve_prefix
+from ..providers import PROVIDERS
+
+logger = logging.getLogger(__name__)
+
+
+def run(args) -> None:
+    asyncio.run(_get(args))
+
+
+def _parse_args(args) -> tuple:
+    """Parse positional args into (vault, item, field).
+
+    Supports:
+      ["item"]                -> (default, item, None)
+      ["vault", "item"]      -> (vault, item, None)
+      ["vault", "item", "f"] -> (vault, item, f)
+      ["vault/item"]         -> resolve via slash
+      ["vault/item/field"]   -> resolve via slash
+    """
+    parts = args.args
+    config = ensure_config()
+    default_vault = get_default_vault(config)
+
+    # If single arg with slashes, use resolver
+    if len(parts) == 1 and "/" in parts[0]:
+        return resolve(parts[0], default_vault)
+
+    if len(parts) == 1:
+        # Could be just an item name (default vault)
+        # Or could be a vault name if it matches a vault
+        vaults = list(config.get("vaults", {}).keys())
+        if parts[0] in vaults:
+            # Ambiguous: is it a vault or an item in default vault?
+            # Check if it's also an item in default vault
+            default_items = config.get("vaults", {}).get(default_vault, {}).get("items", {})
+            if parts[0] in default_items:
+                return default_vault, parts[0], None
+            # It's a vault name but no item specified
+            print(f"Error: vault '{parts[0]}' specified but no item name.", file=sys.stderr)
+            print(f"Usage: dv get {parts[0]} <item>", file=sys.stderr)
+            sys.exit(1)
+        return default_vault, parts[0], None
+    elif len(parts) == 2:
+        return parts[0], parts[1], None
+    elif len(parts) == 3:
+        return parts[0], parts[1], parts[2]
+    else:
+        print("Error: too many arguments. Usage: dv get [vault] <item> [field]", file=sys.stderr)
+        sys.exit(1)
+
+
+async def _get(args) -> None:
+    config = ensure_config()
+    vault, item_name, field = _parse_args(args)
+    logger.debug("Resolved: vault=%s item=%s field=%s", vault, item_name, field)
+
+    item = get_item(config, vault, item_name)
+    if not item:
+        print(f"Error: item '{item_name}' not found in vault '{vault}'.", file=sys.stderr)
+        sys.exit(1)
+
+    kind = item.get("kind", "static")
+
+    if kind == "oidc" and field is None:
+        value = await _get_oidc_token(item, vault, item_name)
+    elif kind == "oidc" and field == "access_token":
+        value = await _get_oidc_token(item, vault, item_name)
+    else:
+        resolved_field = field or _primary_field(item)
+        if not resolved_field:
+            print(f"Error: item '{item_name}' has no fields.", file=sys.stderr)
+            sys.exit(1)
+        value = get_secret(vault, item_name, resolved_field)
+        if value is None:
+            print(
+                f"Error: no secret for {vault}/{item_name}/{resolved_field}. "
+                "Run 'dv set' to store it.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    if getattr(args, "json", False):
+        print(json_mod.dumps({"vault": vault, "item": item_name, "field": field, "value": value}))
+    else:
+        print(value)
+
+
+async def _get_oidc_token(item: dict, vault: str, item_name: str) -> str:
+    provider_name = item.get("provider", "keycloak")
+    provider = PROVIDERS.get(provider_name)
+    if not provider:
+        print(f"Error: unknown OIDC provider '{provider_name}'.", file=sys.stderr)
+        sys.exit(1)
+
+    item_config = item.get("config", {})
+    auth_type = item_config.get("auth_type", "user")
+    secret_field = "client_secret" if auth_type == "client" else "password"
+    secret = get_secret(vault, item_name, secret_field)
+    if secret is None:
+        print(
+            f"Error: no {secret_field} in keyring for {vault}/{item_name}. "
+            "Run 'dv setup' to configure.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return await provider.get_token(item_config, secret)
+
+
+def _primary_field(item: dict) -> str:
+    fields = item.get("fields", [])
+    if isinstance(fields, list) and fields:
+        return fields[0]
+    if isinstance(fields, dict) and fields:
+        return next(iter(fields))
+    return "value"