BioKVBeta

A biometric key-value store
for your Mac.

Store and retrieve secrets from your terminal, backed by Apple’s Data Protection Keychain. BioKV doesn’t just put a Touch ID prompt in front of your secrets. macOS enforces authentication through native Keychain access controls.

Download BioKV for Mac 210 KB

Apple Silicon · macOS 11+ · Signed & notarized

$ biokv --help
Usage: biokv COMMAND [ARGS]

Commands:
  add NAMESPACE/KEY [--policy POLICY]  (stdin: value)
  get NAMESPACE/KEY
  delete NAMESPACE/KEY
  list

Policies:
  biometryAny         Touch ID; survives enrollment changes (default)
  biometryCurrentSet  Touch ID; enrollment changes invalidate access
  userPresence        Touch ID or Mac login password

01 / SYSTEM-ENFORCED AUTHENTICATION

Protection enforced by macOS.

Access is controlled by macOS Keychain Services, not application logic. The system enforces the secret’s authentication policy before releasing its value.

Secrets stay in Apple’s Data Protection Keychain on your Mac. They’re bound to your device and don’t sync to iCloud Keychain.

Touch ID is required by default, with no Mac login-password fallback. Your Mac must be unlocked to retrieve secrets.

02 / FLEXIBLE ACCESS POLICIES

Choose how you authenticate.

The default, biometryAny, requires Touch ID and survives fingerprint enrollment changes. Choose biometryCurrentSet to invalidate access when enrollment changes, or userPresence to allow Touch ID or your Mac login password.

Set the policy when adding a secret. Keep a recovery copy elsewhere before using biometryCurrentSet.

USAGE

Built for your terminal workflow.

Initial setup

Keep BioKV.app intact in /Applications. The bundle contains the provisioning profile required for Keychain access. Use a symlink to make biokv available on your PATH instead of copying out the executable.

# Once installed, create a symlink to biokv in a directory in your PATH, for example:
$ ln -s /Applications/BioKV.app/Contents/MacOS/biokv ~/.local/bin/biokv

Example using age file encryption

# Generate an age identity and store it in BioKV.
$ age-keygen | biokv add age/backup
Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# Encrypt a backup using the public key printed above.
$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age

# Retrieve the identity with Touch ID and decrypt.
$ biokv get age/backup | age --decrypt -i - data.tar.gz.age > data.tar.gz
macOS Touch ID prompt asking to allow BioKV to unlock age/backup.

Example using GitHub CLI

# Copy your GitHub token, then store it in BioKV.
$ pbpaste | biokv add github/alice/token

# Clear the clipboard.
$ pbcopy < /dev/null

# Retrieve the token with Touch ID and check pull request status.
$ GH_TOKEN="$(biokv get github/alice/token)" gh pr status

Example using Stripe CLI

# Copy your Stripe API key, then store it in BioKV (enrollment changes invalidate access).
$ pbpaste | biokv add stripe/acme/api-key --policy biometryCurrentSet

# Clear the clipboard.
$ pbcopy < /dev/null

# Retrieve the key with Touch ID and list customers.
$ STRIPE_API_KEY="$(biokv get stripe/acme/api-key)" stripe customers list

Example using AWS CLI

# BioKV already holds the AWS credential JSON at aws/acme/credentials.
$ cat ~/.aws/config
[profile acme]
credential_process = /Users/alice/.local/bin/biokv get aws/acme/credentials

# Let AWS retrieve the credentials with Touch ID and list S3 buckets.
$ aws --profile acme s3 ls

Example using OpenAI CLI

# Copy your OpenAI API key, then store it in BioKV.
$ pbpaste | biokv add openai/acme/api-key

# Clear the clipboard.
$ pbcopy < /dev/null

# Retrieve the key with Touch ID and send a prompt.
$ OPENAI_API_KEY="$(biokv get openai/acme/api-key)" \
    openai responses create --model gpt-6-astra --input "Say hello."

Example using Claude Code

# Copy your Anthropic API key, then store it in BioKV.
$ pbpaste | biokv add anthropic/acme/api-key

# Clear the clipboard.
$ pbcopy < /dev/null

# Configure Claude Code to retrieve the API key through BioKV.
$ cat ~/.claude/settings.json
{
  "apiKeyHelper": "biokv get anthropic/acme/api-key"
}

# Start Claude Code using API-key authentication.
$ claude

Example using Restic backups

# Generate a random password directly into BioKV.
$ openssl rand -base64 32 | biokv add restic/backup

# Initialize a new repository using the password retrieved with Touch ID.
$ restic -r /Volumes/Backup/restic --password-command 'biokv get restic/backup' init

# Let restic retrieve the password with Touch ID and back up your data.
$ restic -r /Volumes/Backup/restic --password-command 'biokv get restic/backup' backup ~/data

HOW IT WORKS

The authentication policy lives with the secret, not in the app.

macOS has two Keychain implementations: the legacy file-based Keychain and the newer Data Protection Keychain. They use different access-control models, as Apple explains in On Mac keychain APIs and implementations.

The legacy file-based Keychain can be accessed through the security command or Apple’s Keychain APIs. Depending on the item’s access settings and whether the Keychain is unlocked, a read may require a password or proceed without a prompt. This implementation does not support attaching a Touch ID requirement to an item.

Several tools add a Touch ID check to this workflow as an application-level gate. When storing a secret, they can configure its access control list (ACL) to trust their executable. This allows subsequent reads without an additional Keychain prompt while the Keychain is unlocked. Before reading the value, they use LocalAuthentication to request Touch ID. The biometric check is enforced by application code; the Keychain authorizes the executable rather than requiring Touch ID for the item itself.

Unlike the legacy implementation, the Data Protection Keychain allows a SecAccessControl policy to be attached to an item when it is stored. Keychain Services enforces that policy before releasing the value. Authentication is part of retrieving the secret itself.

Integrating with the Data Protection Keychain involves additional requirements: a signed Keychain access-group entitlement, which Apple must authorize through a provisioning profile. Creating that profile requires a Developer ID Application certificate, which in turn requires a paid Apple Developer Program membership.

BioKV handles this setup, making Keychain-enforced authentication available from your terminal.

BioKV

Your secrets. Your fingerprint. Your Mac.