icoretech/warden-mcp

npm version ghcr CI license

Programmatic Vaultwarden/Bitwarden vault management over MCP (Model Context Protocol), backed by the official Bitwarden CLI (bw).

This project exists to let agents and automation create/search/read/update/move vault items without re-implementing Bitwarden’s client-side crypto.

Published package: @icoretech/warden-mcp

Highlights

• MCP Streamable HTTP endpoint at /sse (GET/POST; DELETE intentionally unsupported) + health check at GET /healthz
• Runtime guardrail metrics at GET /metricsz
• Item types: login, secure note, card, identity, plus an SSH key convention (secure note + standard fields)
• Attachments: create/delete/download
• Organization + collection helpers (list + org-collection CRUD)
• Safe-by-default: item reads are redacted unless explicitly revealed; secret helper tools return null unless reveal: true
• Strong fit for LLM automation: pair it with a browser-capable MCP host so an agent can fetch credentials, complete sign-in flows, read TOTP codes, and keep automating after login

Text-Only MCP Client Behavior

Some MCP hosts, including agent shells that optimize tool output for the model, only forward content[] text blocks and do not expose structuredContent to the agent. warden-mcp therefore mirrors the non-secret identifiers needed for follow-up calls into visible text by default.

For search/list tools, the text output includes concise rows with stable ids and safe metadata such as names, item type, username, URI values, organization id, folder id, and collection ids. Secret fields are not included in those summaries. Create/update/move/restore helpers that return a folder, collection, or item use concise visible summaries with reusable ids plus safe item metadata, including nested login username/URI values and attachment metadata where present. Delete helpers include the requested ids when no object is returned.

For scalar helper tools, the text output follows the reveal contract:

• encode, get_uri, and get_exposed show their returned scalar value
• get_username shows the username because Bitwarden treats it as non-secret
• get_password, get_totp, and get_notes show not revealed unless you pass reveal: true
• generate and generate_username follow the same reveal contract: they show generated: not revealed by default and the generated value only with reveal: true
• get_password_history shows not revealed unless you pass reveal: true
• Send helpers mirror their returned Send payloads into visible text so text-only clients can use created Send links, fetched Send metadata, received text, and file-download metadata without reading structuredContent
• if NOREVEAL=true or KEYCHAIN_NOREVEAL=true, revealed values are still suppressed server-side

When a lookup term matches multiple login items, keychain_get_username and revealed keychain_get_password return an AMBIGUOUS_LOOKUP error with visible candidate ids. Retry with term set to an exact candidate id, or call get_item with that id.

If KEYCHAIN_TEXT_COMPAT_MODE=structured_json is enabled, supported success and ambiguity/error results mirror their structuredContent into the visible text as serialized JSON instead of the human summaries.

LLM Automation Use Case

warden-mcp is not only useful for vault administration. A very practical use case is pairing it with an LLM that can also drive a browser.

That lets the agent do end-to-end authenticated workflows such as:

• open a site or backoffice in the browser
• read the right login from Vaultwarden or Bitwarden
• fill username and password without hardcoding secrets in prompts or config
• retrieve a current TOTP code with keychain_get_totp for TOTP-based MFA
• continue the real task after login, such as navigation, data entry, exports, or routine admin work

In practice, this is what makes the server useful for full automation, not just secret lookup. The same MCP session that gives the model browser control can also give it scoped access to the credentials and MFA material needed to finish the workflow.

Runtime Requirement

Requires Node.js 24+ and npm when running from npm or source. The Docker image already includes the supported Node runtime.

At runtime, this package shells out to the official Bitwarden CLI, bw.

Runtime resolution order:

• BW_BIN if you set it explicitly
• bundled @bitwarden/cli optional dependency if it is present
• system bw from PATH

That means package installation can succeed even when the optional dependency is skipped by the environment. In that case you must install bw separately or point BW_BIN to it.

Explicit fallback install:

npm install -g @bitwarden/[email protected]

Or run with an explicit binary path:

BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest

warden-mcp intentionally bundles a vetted @bitwarden/cli version (currently 2026.5.0) instead of blindly following the newest upstream CLI on every release. New bw releases can change login and unlock behavior in ways that break automation, so bw upgrades should be smoke-tested against real Vaultwarden flows before bumping the bundled version. Official Bitwarden compatibility is intended, but it is not continuously proven in CI without a real Bitwarden tenant.

This repository's compose smoke exercises both direct bw auth flows and the MCP/SDK layers with username/password auth plus user API-key auth against a real local Vaultwarden, so @bitwarden/cli bumps do not rely on unit coverage alone. The bundled postinstall compatibility shim rewrites the affected build/bw.js login strategies in place so the same Vaultwarden fallback can survive compatible CLI bumps without a version-stamped patch artifact.

Install And Run

Choose a transport

• Use --stdio or WARDEN_MCP_STDIO=true when you want a local MCP host to spawn warden-mcp directly with one fixed Bitwarden profile
• Use default HTTP mode when you want one running warden-mcp service to serve multiple clients or multiple Bitwarden profiles via per-request X-BW-* headers

Local stdio mode

npx -y @icoretech/warden-mcp@latest --stdio

For stdio mode, you must provide Bitwarden credentials up front via env vars:

BW_HOST=https://vaultwarden.example.com \
[email protected] \
BW_PASSWORD='your-master-password' \
npx -y @icoretech/warden-mcp@latest --stdio

API key login works too:

BW_HOST=https://vaultwarden.example.com \
BW_CLIENTID=user.xxxxx \
BW_CLIENTSECRET=xxxxx \
BW_PASSWORD='your-master-password' \
npx -y @icoretech/warden-mcp@latest --stdio

Shared HTTP mode

Start one long-lived MCP server:

npx -y @icoretech/warden-mcp@latest

Verify it is up:

curl -fsS http://localhost:3005/healthz

This mode is what makes warden-mcp different from a simple local wrapper:

• Bitwarden/Vaultwarden credentials and profile selection are resolved per request via X-BW-* headers
• MCP Streamable HTTP sessions are stateful and tracked by mcp-session-id
• per-profile bw state is kept server-side under KEYCHAIN_BW_HOME_ROOT
• one running server can front different vault hosts or different identities without restarting
• it fits shared-agent and gateway setups much better than per-client local processes

Docker

docker run --rm \
  -p 127.0.0.1:3005:3005 \
  -v warden-mcp-data:/data \
  ghcr.io/icoretech/warden-mcp:latest

The production image runs as the non-root node user (uid/gid 1000), sets HOME=/data, and stores Bitwarden profile state under /data/bw-profiles by default. If you use a bind mount instead of the named volume above, make it writable by uid/gid 1000.

Global install

npm install -g @icoretech/warden-mcp@latest
warden-mcp

Connect From MCP Hosts

For local MCP hosts, stdio is the most portable option.

npx -y @icoretech/warden-mcp@latest --stdio

The examples below use Bitwarden API-key auth. If you prefer username/password login, replace BW_CLIENTID + BW_CLIENTSECRET with BW_USER.

CLI-based hosts

These hosts let you register warden-mcp directly from the command line:

# Codex
codex mcp add warden \
  --env BW_HOST=https://vaultwarden.example.com \
  --env BW_CLIENTID=user.xxxxx \
  --env BW_CLIENTSECRET=xxxxx \
  --env BW_PASSWORD='your-master-password' \
  -- npx -y @icoretech/warden-mcp@latest --stdio

# Claude Code
claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'

JSON config hosts

These hosts all use the same stdio payload shape. Only the config file location changes:

• Codex: ~/.codex/config.toml
• Cursor: ~/.cursor/mcp.json or .cursor/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Shared JSON shape:

{
  "mcpServers": {
    "warden": {
      "command": "npx",
      "args": ["-y", "@icoretech/warden-mcp@latest", "--stdio"],
      "env": {
        "BW_HOST": "https://vaultwarden.example.com",
        "BW_CLIENTID": "user.xxxxx",
        "BW_CLIENTSECRET": "xxxxx",
        "BW_PASSWORD": "your-master-password"
      }
    }
  }
}

Codex uses TOML instead of JSON:

[mcp_servers.warden]
command = "npx"
args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
startup_timeout_sec = 30

[mcp_servers.warden.env]
BW_HOST = "https://vaultwarden.example.com"
BW_CLIENTID = "user.xxxxx"
BW_CLIENTSECRET = "xxxxx"
BW_PASSWORD = "your-master-password"

startup_timeout_sec = 30 is a practical Codex default when using npx, because a cold first launch can spend several seconds downloading and unpacking the package before MCP initialization begins.

Shared HTTP connections

If your MCP host supports Streamable HTTP with custom headers, you can connect to one long-lived warden-mcp service instead of spawning a local stdio process.

Start the shared server:

npx -y @icoretech/warden-mcp@latest

GET /healthz and GET /metricsz are liveness/guardrail endpoints and do not validate Bitwarden credentials:

curl -fsS http://localhost:3005/healthz

Bitwarden-backed MCP tool calls must include these headers unless KEYCHAIN_ALLOW_ENV_FALLBACK=true is enabled:

• X-BW-Host — HTTPS origin only; no credentials, path, query, or fragment
• X-BW-Password
• either X-BW-ClientId + X-BW-ClientSecret, or X-BW-User / X-BW-Username
• optional X-BW-Unlock-Interval in seconds; default 300

Example MCP endpoint:

http://localhost:3005/sse?v=2

This shared-server mode is useful when:

• one MCP gateway needs to front multiple Bitwarden profiles
• you want to rotate vault credentials per request instead of per process
• you are integrating from a custom client or agent host that can attach HTTP headers
• you want one always-on service instead of each editor spawning its own bw-backed subprocess

Headerless SSE clients (claude.ai web, similar hosts)

Some web MCP hosts can connect to a Streamable HTTP / SSE endpoint but cannot attach custom X-BW-* headers. In that case, run warden-mcp as a single-tenant shared server with fixed server-side credentials and explicit env fallback enabled:

BW_HOST=https://vaultwarden.example.com \
BW_CLIENTID=user.xxxxx \
BW_CLIENTSECRET=xxxxx \
BW_PASSWORD='your-master-password' \
KEYCHAIN_ALLOW_ENV_FALLBACK=true \
npx -y @icoretech/warden-mcp@latest

Some hosted or browser-based MCP clients expect the server URL to be available over HTTPS rather than plain http://localhost:3005/....

If you are running warden-mcp locally, that usually means putting one of these in front of it:

• a local HTTPS reverse proxy in front of warden-mcp
• a temporary tunnel such as Cloudflare Tunnel, ngrok, or Tailscale Funnel

Then point the client at the HTTPS endpoint, for example:

https://warden-mcp.example.com/sse?v=2

This works because headerless HTTP requests can inherit the server's own BW_* configuration when KEYCHAIN_ALLOW_ENV_FALLBACK=true. You can use BW_USER + BW_PASSWORD here as well; the example above shows the API-key variant because it is the default convention used elsewhere in this README.

Important limits:

• this is single-tenant only: every headerless client gets the same vault identity
• per-request profile switching does not work in this mode
• if a client can send X-BW-* headers, those headers still take priority over the server env
• anyone who can reach that endpoint inherits that vault access, so keep it behind trusted network access, VPN, tunnel access policies, IP allowlists, or another private boundary

Client examples for shared HTTP mode:

# Claude Code
claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2","headers":{"X-BW-Host":"https://vaultwarden.example.com","X-BW-ClientId":"user.xxxxx","X-BW-ClientSecret":"xxxxx","X-BW-Password":"your-master-password"}}'

// Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "warden": {
      "url": "http://localhost:3005/sse?v=2",
      "headers": {
        "X-BW-Host": "https://vaultwarden.example.com",
        "X-BW-ClientId": "user.xxxxx",
        "X-BW-ClientSecret": "xxxxx",
        "X-BW-Password": "your-master-password"
      }
    }
  }
}

Codex currently fits better with stdio here, because its MCP config supports a bearer token env var for remote servers but not arbitrary custom X-BW-* header injection.

Verify bw is available

bw --version

If that fails after install, your environment likely skipped the optional @bitwarden/cli dependency. Install it explicitly:

npm install -g @bitwarden/[email protected]

How It Works

The server executes bw commands on your behalf:

• In HTTP mode, Bitwarden/Vaultwarden credentials are provided via HTTP headers for tool calls. Env-var fallback is disabled by default; set KEYCHAIN_ALLOW_ENV_FALLBACK=true only for single-tenant HTTP deployments.
• In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from BW_* env vars at startup.
• The server maintains per-profile bw state under KEYCHAIN_BW_HOME_ROOT and pins BITWARDENCLI_APPDATA_DIR inside that profile so the Bitwarden CLI keeps a stable local device/app identity across restarts instead of looking like a fresh client every time.
• Writes call bw sync before mutations by default; set KEYCHAIN_SYNC_ON_WRITE=false to skip that pre-write sync. Manual sync is also exposed as keychain_sync.

Timeout handling is also process-tree aware: if a bw command hangs, warden-mcp kills the full spawned process group rather than only the direct parent process. That prevents timed-out auth attempts from leaving orphaned bw/shell child processes behind.

Bitwarden credential inputs

• X-BW-Host / BW_HOST (must be an HTTPS origin, for example https://vaultwarden.example.com; no path, query, fragment, or embedded credentials)
• X-BW-Password / BW_PASSWORD (master password; required to unlock)
• Either:
  • X-BW-ClientId + X-BW-ClientSecret / BW_CLIENTID + BW_CLIENTSECRET (API key login), or
  • X-BW-User / X-BW-Username / BW_USER / BW_USERNAME (email for user/pass login; still uses the master password)
• Optional unlock interval:
  • X-BW-Unlock-Interval / BW_UNLOCK_INTERVAL in seconds; default 300

Security Model

There is no built-in auth layer in v1. Run it only on a trusted network boundary (localhost, private subnet, VPN, etc.).

Credential resolution:

• HTTP mode requires X-BW-* headers before Bitwarden-backed tools can run by default. /healthz and /metricsz do not validate vault credentials.
• Stdio mode reads BW_* env vars at startup (single-tenant).
• To allow HTTP mode to fall back to server env vars when headers are absent (single-tenant HTTP), set KEYCHAIN_ALLOW_ENV_FALLBACK=true. Security warning: this means any client that can reach the HTTP endpoint gets full vault access without providing credentials. Only use this behind network-level access control.

Runtime and safety controls:

• Set PORT to change the HTTP port (default 3005).
• Set WARDEN_MCP_HOST to bind the HTTP server to a specific interface, for example 127.0.0.1 for local-only access.
• Set WARDEN_MCP_STDIO=true as an env-var alternative to --stdio.
• Set MCP_APP_NAME to override the advertised MCP server name.
• Tool names default to keychain_*. Override TOOL_PREFIX to change the namespace and TOOL_SEPARATOR to change the separator (default _, set . for legacy clients).
• Set KEYCHAIN_BW_HOME_ROOT to change where per-profile bw state is stored.
• Set KEYCHAIN_SYNC_ON_WRITE=false to skip the default pre-write bw sync call.
• Set READONLY=true or KEYCHAIN_READONLY=true to hide mutating tools from the advertised MCP catalog and reject direct write calls. This covers item/folder/org collection writes, Sends, attachments, batch creates/deletes, URI updates, moves, and restores.
• Set NOREVEAL=true or KEYCHAIN_NOREVEAL=true to force all reveal parameters to false server-side. Clients can still request reveal: true, but the server will silently downgrade to redacted output. This prevents prompt injection from tricking an LLM agent into exfiltrating secrets.
• Set KEYCHAIN_TEXT_COMPAT_MODE=structured_json to mirror supported structured tool results into TextContent as serialized JSON. This is useful for text-only MCP clients that ignore structuredContent, but it also duplicates revealed secrets into the plain-text transcript.

Session guardrails:

• KEYCHAIN_SESSION_MAX_COUNT (default 32)
• KEYCHAIN_SESSION_TTL_MS (default 900000)
• KEYCHAIN_SESSION_SWEEP_INTERVAL_MS (default 60000)
• KEYCHAIN_MAX_HEAP_USED_MB (default 1536, set 0 to disable memory fuse)
• KEYCHAIN_METRICS_LOG_INTERVAL_MS (default 0, disabled)

Redaction defaults (item reads):

• Login: password, totp
• Card: number, code
• Identity: ssn, passportNumber, licenseNumber
• Custom fields: hidden fields (Bitwarden type: 1)
• SSH key convention: custom field private_key is always redacted
• Attachments: attachments[].url (signed download URL token)
• Password history: passwordHistory[].password

Reveal rules:

• Tools accept reveal: true where applicable (default is false).
• Secret helper tools (get_password, get_totp, get_notes, generate, generate_username, get_password_history) return structuredContent.result = { kind, value, revealed }.
  • When reveal is omitted/false, value is null (or historic passwords are null) and revealed: false.

Production Deployment Checklist

If you run warden-mcp beyond local development, review these items:

1. TLS everywhere. Always terminate TLS in front of the HTTP endpoint. X-BW-* headers carry master passwords in cleartext — without TLS they are visible to anyone on the network.

2. Network isolation. Bind or publish the server only on a trusted interface, for example WARDEN_MCP_HOST=127.0.0.1, Docker -p 127.0.0.1:3005:3005, a firewall, VPN, or an authenticated reverse proxy. The service has no built-in authentication; anyone who can reach /sse can issue vault operations.

3. Do not enable KEYCHAIN_ALLOW_ENV_FALLBACK on shared networks. This flag makes the server's own vault credentials available to any HTTP client that omits headers. Only use it in single-tenant setups where the network is fully trusted.

4. Enable READONLY=true or KEYCHAIN_READONLY=true when writes are not needed. This hides mutating tools from the advertised MCP catalog and rejects direct write calls at the MCP layer, limiting blast radius if an agent or client is compromised.

5. Persist and restrict filesystem access to the configured KEYCHAIN_BW_HOME_ROOT. In Docker the default is /data/bw-profiles; on host runs it defaults to ${HOME}/bw-profiles. Ensure the profile directory is not world-readable and is mounted with appropriate permissions (the Docker image runs as non-root uid/gid 1000).

6. Disable debug logging in production. KEYCHAIN_DEBUG_BW and KEYCHAIN_DEBUG_HTTP emit request details and CLI invocations to stdout. Debug logs may include session metadata and request structure. Keep them off unless actively troubleshooting.

7. Set NOREVEAL=true when secrets should never leave the server. This forces all reveal parameters to false server-side, regardless of what the client requests. Use this when the MCP host is an LLM agent that could be influenced by prompt injection — it prevents tricked agents from exfiltrating passwords or TOTP codes.

8. Monitor /metricsz. The endpoint is intentionally unauthenticated (for scraper compatibility) but exposes session counts, heap usage, and rejection counters. If this data is sensitive in your environment, restrict access at the network level.

9. Only enable KEYCHAIN_TEXT_COMPAT_MODE=structured_json for text-only clients you trust. It improves compatibility with clients that ignore structuredContent, but any revealed secret will also appear in plain-text TextContent, making transcript leakage easier.

Quick Start

Minimal local run

Run the published package in HTTP mode and verify the server is up:

npx -y @icoretech/warden-mcp@latest
curl -fsS http://localhost:3005/healthz

Local Development

Docker Compose

Starts a local Vaultwarden + HTTPS proxy (for bw), bootstraps a test user, and runs the MCP server.

cp .env.example .env
make up

make up keeps the MCP service in the foreground. In another terminal, verify the server is up:

curl -fsS http://localhost:3005/healthz

Run integration tests:

make test

make test now runs both compose-backed auth paths and verifies them at the raw CLI plus MCP/SDK layers:

• user/password login from .env.test
• api-key login from tmp/vaultwarden-bootstrap/apikey.env, generated by the bootstrap step and kept out of git via tmp/

The compose bootstrap step depends on the Playwright Docker image matching the playwright npm package version. If either moves, update the other in the same change.

Optional organization-focused integration stack:

make test-org

Use make up-org, make bootstrap-org, make down-org, and make ps-org when you need to inspect that stack manually.

Run session flood regression locally after a server is already running on http://127.0.0.1:3005 (override with KEYCHAIN_FLOOD_BASE_URL and KEYCHAIN_METRICS_URL when needed):

npm run test:session-regression

Local dev (host)

npm ci
set -a && . ./.env && set +a  # optional; Docker Compose reads .env automatically, host dev does not
npm run dev

For host HTTP mode, vault credentials can still be supplied per request with X-BW-* headers instead of loading them into the server environment.

Useful npm scripts:

Script	Purpose
npm run build	Compile TypeScript to dist/
npm run dev	Watch-mode local HTTP server
npm run start	Run the compiled server from dist/
npm run test	Build, then run all compiled unit tests
npm run test:integration	Build, then run compose-backed integration tests one file at a time
npm run test:coverage	Build, then run Node test coverage
npm run lint	Run Biome autofix plus tsc --noEmit

Tool Reference (v1)

Choosing the right tool

• Start with keychain_search_items when you know a name, URI, username, folder, collection, or item type but not the exact item id. Then call keychain_get_item with the returned id for the full item shape.
• Use keychain_create_logins when you need to create several independent login items in one call; it returns per-item results and can continue after individual failures.
• Use keychain_set_login_uris to replace or merge a login item's URI list without editing the whole item payload.
• Use keychain_delete_items for bulk soft-delete/hard-delete by id with per-id results.
• Personal folder tools manage one user's vault folders, for example Example Folder. Organization collection tools manage shared organization-scoped collections, for example Example Collection. organizationId is required for keychain_list_org_collections, keychain_create_org_collection, keychain_edit_org_collection, and keychain_delete_org_collection, and optional only for keychain_get_org_collection when you want to narrow a direct id lookup.
• keychain_move_item_to_organization moves an item out of the personal vault and into an organization, optionally assigning collection ids at the same time.
• keychain_send_create is the quick path for text or file Sends through the normal bw send flags, including emails for email-gated access. emails is mutually exclusive with password and does not share the generated Send URL for you. keychain_send_template, keychain_send_create_encoded, and keychain_send_edit are for the full Bitwarden Send JSON template or an encoded edit payload.
• keychain_send_get returns owned Send metadata, including accessUrl, or text content with text=true. To download a file Send, pass that accessUrl to keychain_receive with downloadFile=true; the bundled bw send get command does not implement file download output.
• Pass reveal: true only to tools that can return secrets, such as password, TOTP, notes, generated secrets, password history, or full item reads. By default these stay redacted. Text-only MCP clients follow the same reveal contract described in Text-Only MCP Client Behavior, and server-side NOREVEAL settings still win.

Vault/session:

• keychain_status
• keychain_sync (pull latest vault data from server via bw sync)
• keychain_sdk_version (returns the Bitwarden CLI version reported by bw --version)
• keychain_encode (base64-encode a string via bw encode)
• keychain_generate, keychain_generate_username (return generated values only when reveal: true)

Items:

• keychain_search_items, keychain_get_item, keychain_update_item
• keychain_create_login, keychain_create_logins, keychain_set_login_uris
• keychain_create_note, keychain_create_card, keychain_create_identity, keychain_create_ssh_key
• keychain_delete_item, keychain_delete_items, keychain_restore_item

Folders:

• keychain_list_folders, keychain_create_folder, keychain_edit_folder, keychain_delete_folder

Orgs/collections:

• keychain_list_organizations, keychain_list_collections
• keychain_list_org_collections, keychain_create_org_collection, keychain_edit_org_collection, keychain_delete_org_collection
• keychain_move_item_to_organization

Attachments:

• keychain_create_attachment, keychain_delete_attachment, keychain_get_attachment
• keychain_get_item exposes safe attachment metadata (id, fileName, size) while redacting signed download URLs, so clients can discover the exact attachment id before downloading
• keychain_get_attachment accepts an attachment id or an unambiguous filename and returns { filename, bytes, contentBase64 }; decode contentBase64 locally when you need the original file bytes

Sends:

• keychain_send_list, keychain_send_template, keychain_send_get
• keychain_send_create (quick create via bw send, including optional emails)
• keychain_send_create_encoded, keychain_send_edit (advanced create/edit via bw send create|edit)
• keychain_send_remove_password, keychain_send_delete
• keychain_receive (receive shared Sends and download file Send bytes)

Direct “bw get …” helpers:

• keychain_get_username (returns { kind:"username", value, revealed:true })
• keychain_get_password / keychain_get_totp / keychain_get_notes (only return real values when reveal: true)
• keychain_get_uri, keychain_get_exposed
• keychain_get_folder, keychain_get_collection, keychain_get_organization, keychain_get_org_collection
• keychain_get_password_history (only returns historic passwords when reveal: true)

Known Limitations

• bw list items --search (and thus keychain_search_items) does not reliably search inside custom field values.
• SSH keys are stored as secure notes in v1 (until bw supports native SSH key item creation).
• High-risk CLI features are intentionally not exposed yet (export/import).

Contributing

See AGENTS.md for repo guidelines, dev commands, and testing conventions.