ai-secrets
AI-friendly secrets management CLI using OS-native encryption.
Supported Backends:
Windows Credential Manager • macOS Keychain • Linux Secret Service
Features
- 🔒 Secure — OS-native keyring encryption
- 🤖 AI-friendly — Consistent JSON with
successflags,--revealmode - 📊 Flexible — JSON, Table, and Bash output formats
- 🎯 Type-safe — Full type hints and validation
- ✅ Tested — 34 passing tests
- 🚀 Simple — Clean API with proper error handling
Installation
# From PyPI
pip install ai-secrets
# Or with uv
uv add ai-secrets
# Development install
git clone https://github.com/BjornBethge/ai-secrets.git
cd ai-secrets
uv sync
Quick Start
# Store a secret
ai-secrets set HF_TOKEN "hf_your_token_here"
# Check if secret exists
ai-secrets get HF_TOKEN
# List all secrets (names only)
ai-secrets list
# AI-friendly: Get secret value in JSON
ai-secrets get HF_TOKEN --reveal -f json
# Delete secret
ai-secrets delete HF_TOKEN --yes
Note: The command
secretsis also available as an alias forai-secrets.
Commands
set — Store secret
ai-secrets set API_KEY "sk-1234" -f json
# {"success": true, "name": "API_KEY", "message": "..."}
get — Retrieve secret
# Check existence only
ai-secrets get API_KEY
# ✓ Secret 'API_KEY' exists
# For AI workflows (returns value in JSON)
ai-secrets get API_KEY --reveal -f json
# {"success": true, "name": "API_KEY", "exists": true, "value": "sk-1234"}
# For humans (prints to terminal)
ai-secrets get API_KEY --print
list — List all secrets
ai-secrets list -f json
# {"success": true, "secrets": ["API_KEY", "HF_TOKEN"], "count": 2}
delete — Delete secret
ai-secrets delete API_KEY --yes -f json
# {"success": true, "name": "API_KEY", "deleted": true}
status — Show manager status
ai-secrets status -f json
# {"success": true, "service_name": "ai-secrets", "secret_count": 3, ...}
export — Export as environment variables
# Bash format (prints export statements)
ai-secrets export -f bash
# export API_KEY=sk-1234
# export HF_TOKEN=hf_xxx
# JSON format
ai-secrets export -f json
# {"success": true, "secrets": {"API_KEY": "sk-1234", ...}, "count": 2}
AI-Friendly JSON
All JSON responses follow a consistent structure:
Success:
{
"success": true,
"name": "API_KEY",
...
}
Error:
{
"success": false,
"error": "Secret 'MISSING' not found",
"name": "MISSING"
}
The --reveal flag:
- Works only with
-f json - Returns actual secret value
- Designed for AI workflows where value is needed programmatically
Multi-Project Support
Use --service-name to isolate secrets per project:
# Production secrets
ai-secrets --service-name myapp-prod set DB_PASSWORD "secret"
# Development secrets
ai-secrets --service-name myapp-dev set DB_PASSWORD "dev123"
# Custom metadata location
ai-secrets --service-name myapp --base-dir .secrets set API_KEY "key"
Python API:
from ai_secrets.storage import SecretsStore
from pathlib import Path
# Per-environment stores
prod_store = SecretsStore(service_name="myapp-prod")
dev_store = SecretsStore(service_name="myapp-dev", base_dir=Path(".secrets"))
# Set and get secrets
prod_store.set("API_KEY", "sk-prod-xxx")
print(prod_store.get("API_KEY")) # "sk-prod-xxx"
# List all secret names
secrets = prod_store.list_names() # ["API_KEY", ...]
# Export as dict
env_vars = prod_store.export_env() # {"API_KEY": "sk-prod-xxx", ...}
# Delete a secret
prod_store.delete("API_KEY")
Direct keyring usage:
import keyring
# Store secret (basic keyring API)
keyring.set_password("myapp", "API_KEY", "secret-value")
# Get secret
value = keyring.get_password("myapp", "API_KEY")
# Delete secret
keyring.delete_password("myapp", "API_KEY")
Why use ai-secrets instead of raw keyring?
- ✅ Secret name management (list all secrets)
- ✅ Metadata tracking (knows what secrets exist)
- ✅ Multi-environment support (
--service-name)- ✅ JSON export for AI workflows
- ✅ CLI convenience
Development
# Install dependencies
uv sync
# Run tests
uv run pytest tests/ -v
Notes
- Default service name:
ai-secrets(before v0.1.0:ai-keys) - Metadata stored in:
~/.secrets/metadata_<service-name>.json(only names, not values) - Secret values stored in: OS keyring (encrypted)
- Each service has its own metadata file to avoid conflicts
export -f bashprints warning to stderr- Linux/KeePassXC: May prompt for database unlock
Metadata
Release files for ai-secrets 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_secrets-0.1.2.tar.gz | 46.7 kB | Without provenance | Details for ai_secrets-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_secrets-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for ai_secrets-0.1.2-py3-none-any.whl |
Total release size: 55.7 kB
Release files / ai_secrets-0.1.2.tar.gz
| Download URL | ai_secrets-0.1.2.tar.gz |
|---|---|
| Size | 46.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48a6a74175c295416b016a48e743f6443c3d9e805f9fbe530555348cdb4f8d21
|
|
BLAKE2b-256 checksum How to use checksums |
585b508a444c4d8528717103c4d107aba3fc5bce5593d261e83d706805ca71ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / ai_secrets-0.1.2-py3-none-any.whl
| Download URL | ai_secrets-0.1.2-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
17faf617e610112aeddf842180a1c501ce9dcf6b77bfbf6ec33f084477066941
|
|
BLAKE2b-256 checksum How to use checksums |
4286f375ae0a1029c21baf7dfd45ca2f98187c321d8051f7b1a3b1b33b2bf87b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for ai-secrets 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.