vaultsh: CLI Wrapper for HashiCorp Vault

After deploying Vault with Ansible and using it to supply the Ansible Vault password via a wrapper script, I found myself running the same vault commands over and over: log in with OIDC, check if my token was still valid, read or write KV secrets, run the occasional diagnostic. The steps were simple but repetitive, and I wanted one interactive tool instead of remembering a long list of flags and paths.

So I built vaultsh – a small CLI wrapper for HashiCorp Vault that covers these daily admin tasks and uses native interactive menus (arrow keys, Enter, ESC, number/letter shortcuts) so you can pick roles and paths without external tools.

The Problem

Working with Vault from the CLI often looks like this:

• Login: vault login -method=oidc role=... – and you have to remember or look up the role name and any role-specific options.
• Session check: Is my token still valid? Which role did I use? You run vault token lookup or check env vars.
• KV read/write: Different paths for different projects, so you either type long paths or keep a cheat sheet.
• Diagnostics: When something fails, you run a few vault status / vault read style commands to see what’s going on.

Individually each command is fine, but the repetition and the need to remember paths and roles made me look for a single entry point that could do the common operations with less typing and fewer mistakes.

Why a Wrapper?

A wrapper doesn’t replace the official vault CLI – it sits in front of it and:

• Encapsulates common flows – e.g. “log in with OIDC” with a configurable default role, or “read from this KV path” with a default engine/path.
• Reduces typing – Short subcommands and sensible defaults instead of long invocations.
• Adds structure – Interactive menus for choosing roles, paths, or secrets (no external tools).
• Keeps compatibility – Under the hood it still uses the real vault binary and your existing auth (e.g. VAULT_ADDR, VAULT_TOKEN).

So you get a convenience layer for the 80% case while still being able to drop back to raw vault when needed.

What vaultsh Does

vaultsh is a standalone CLI that supports:

• OIDC login – Configure one or more roles (e.g. in a config file); from the main menu you can log in and optionally pick a role. It runs the appropriate vault login -method=oidc ... for you.
• Session / token check – Quick way to see if you’re logged in, which token you have, and optionally whether it’s still valid (with a configurable KV probe if token lookup returns 403).
• KV read and write – Read or write secrets; specify path and optional field each time. You can also browse KV paths, open “folders” (prefixes), and read secrets from the menu.
• Diagnostics – Helpers that run the usual status and lookup commands so you can quickly see if Vault is reachable and how your session looks.

Menus use arrow keys, Enter, and ESC; you can pick a role, browse KV paths, or select a secret without leaving the terminal. For scripts or one-off commands, use the subcommands instead of the interactive menu.

Usage and Configuration

You run vaultsh via its binary; without a subcommand the interactive main menu starts:

• vaultsh – Main menu: OIDC login (reader/operator roles), browse KV paths, read or write secrets, session check, diagnostics.
• vaultsh session-check – Show whether you’re logged in (token state or KV probe).
• vaultsh read -p <path> [-f <field>] – Read a secret; path required, optional field.
• vaultsh browse – Start the KV path browser.

Configuration (Vault address, roles, optional session-probe path, nav root) lives in a Key=Value config file (~/.config/vaultsh/config) or VAULTSH_* environment variables.

Where to Find It

vaultsh is open source and available on GitHub: github.com/brsksh/vaultsh. You can clone it, build or run it locally, and extend it for your own default paths and roles.

Lessons Learned

Building a thin wrapper around the Vault CLI was enough to make daily use more comfortable without reimplementing Vault’s logic. For OIDC and status/token lookup it still uses the real vault binary; for KV read/write it talks to the Vault API (hvac) directly. Native menus (questionary + rich) keep the tool usable both in scripts (use subcommands like session-check, read) and interactively (main menu with browse and shortcuts). vaultsh is not intended for automation or CI—use the vault CLI there. If you’re running Vault in anger and spend a lot of time in the terminal, a small wrapper like this can pay off quickly.

---

This is the last part of the HashiCorp Vault series: Part 1 introduced what Vault is and how it works, Part 2 covered deploying Vault with Ansible, Part 3 showed how to pull the Ansible Vault password from HashiCorp Vault with a wrapper script, and this part (Part 4) introduced vaultsh for day-to-day Vault management.