LLM Key Ring (lkr)

A secure CLI tool for managing LLM API keys via macOS Keychain. No more plaintext keys in .env files.

$ lkr set openai:prod
Enter API key for openai:prod: ****
Stored openai:prod (kind: runtime)

$ lkr get openai:prod
Copied to clipboard (auto-clears in 30s)
  sk-p...3xYz  (runtime)

$ lkr exec -- python script.py       # Keys injected as env vars (safest)
$ lkr gen .env.example -o .env       # Generate config from template

Why?

Install

# From source
git clone https://github.com/yottayoshida/llm-key-ring.git
cd llm-key-ring
cargo install --path crates/lkr-cli

Requires Rust 1.85+ and macOS (uses native Keychain).

Usage

Store a key

lkr set openai:prod          # Interactive prompt (recommended)
pbpaste | lkr set openai:prod  # From clipboard (avoids hidden-input confusion)

Key names use provider:label format (e.g., openai:prod, anthropic:main).

Retrieve a key

lkr get openai:prod            # Masked display + clipboard (30s auto-clear)
lkr get openai:prod --show     # Show raw value in terminal
lkr get openai:prod --json     # JSON output
lkr get openai:prod --plain    # Raw value only (blocked in non-interactive env)

List keys

lkr list                # Runtime keys only
lkr list --all          # Include admin keys
lkr list --json         # JSON output

Run a command with keys as env vars (recommended)

lkr exec -- python script.py                # Inject all runtime keys
lkr exec -k openai:prod -- curl ...         # Inject specific keys only
lkr exec -k openai:prod -k anthropic:main -- node app.js

Keys are mapped to conventional env var names (e.g., openai:prod → OPENAI_API_KEY) and injected into the child process. Only runtime keys are injected — admin keys are excluded by design. Keys never appear in stdout, files, or clipboard — this is the safest way to pass secrets to programs. Prefer exec over gen whenever possible.

Generate config from template

Use gen when the target program requires a config file and cannot accept env vars:

lkr gen .env.example              # → .env (auto-derived output path)
lkr gen .env.example -o .env.local  # Explicit output path
lkr gen config.json.template      # Works with JSON templates too

.env.example format — keys are auto-resolved by exact env var name match:

OPENAI_API_KEY=your-key-here    # ← resolved from openai:* in Keychain
ANTHROPIC_API_KEY=              # ← resolved from anthropic:*

JSON template format — use explicit {{lkr:provider:label}} placeholders:

{
  "openai_key": "{{lkr:openai:prod}}",
  "anthropic_key": "{{lkr:anthropic:main}}"
}

Generated files are written with 0600 permissions. A warning is shown if the output file is not in .gitignore.

When multiple runtime keys exist for the same provider (e.g., openai:prod and openai:stg), the alphabetically first key is used. A warning lists alternatives. Use {{lkr:provider:label}} placeholders for explicit control.

Delete a key

lkr rm openai:prod         # With confirmation prompt
lkr rm openai:prod --force # Skip confirmation

Check API usage costs

lkr usage openai        # Single provider
lkr usage               # All providers with admin keys
lkr usage --json        # JSON output

Requires an Admin API key registered with --kind admin:

lkr set openai:admin --kind admin

Global flags

lkr <command> --json    # JSON output (all commands)
lkr --help
lkr --version

Supported Providers

lkr gen auto-resolves keys for these providers:

Any provider:label name works with set/get/rm. The provider list above is used for auto-resolution in lkr gen.

Security

Threat Model

See docs/SECURITY.md for the full threat model. Key protections:

Agent IDE Attack Protection

AI coding assistants (Cursor, Copilot, etc.) can be tricked via prompt injection into running commands that exfiltrate secrets. lkr defends against this with three layers:

What TTY guard protects against: non-interactive exfiltration — agents piping --plain/--show output or reading clipboard via pbpaste.

What it does NOT protect against: a user being socially engineered into running --show in their own terminal. Use lkr exec as the default workflow to minimize this surface.

# Layer 1: --plain/--show blocked in pipes (exit code 2)
echo | lkr get openai:prod --plain
# Error: --plain and --show are blocked in non-interactive environments.

# Layer 2: Clipboard copy skipped in non-interactive environments
echo | lkr get openai:prod
# "Clipboard copy skipped (non-interactive environment)."
# → prevents `lkr get key && pbpaste` bypass

# Layer 3: Safe alternatives for automation
lkr exec -- python script.py   # Recommended: keys in env vars only (never stdout/file/clipboard)
lkr gen .env.example -o .env   # Fallback: keys to file (0600), never stdout

Architecture

llm-key-ring/
├── crates/
│   ├── lkr-core/     # Library: KeyStore trait, Keychain, templates, usage API
│   └── lkr-cli/      # Binary: clap CLI (set/get/list/rm/gen/usage/exec)
├── docs/
│   └── SECURITY.md   # Threat model
├── LICENSE-MIT
└── LICENSE-APACHE

All business logic lives in lkr-core. The CLI is a thin wrapper.

Platform Support

Currently macOS only (uses native Keychain via security-framework). The KeyStore trait abstraction is designed for future backend support (Linux libsecret, Windows Credential Manager).

Keychain Storage

Development

# Build
cargo build

# Test
cargo test

# Clippy
cargo clippy -- -D warnings

# Run without installing
cargo run --bin lkr -- list

License

Dual-licensed under MIT or Apache-2.0, at your option.