macOS Keychain for Developers: A Practical Guide

We tried using the macOS security CLI for a month. The goal: stop storing API keys in .env files and use the Keychain instead — encrypted, hardware-backed, free. How hard could it be? It took four minutes to store the first secret. Eleven minutes to figure out why we couldn't read it back. And after a month of fighting with security find-generic-password flags, we gave up and built something better. But the instinct was right. The macOS Keychain is the best credential store most developers never use. The problem was never the Keychain. The problem was the interface. Two keychains, one name Most developers don't realize macOS has two fundamentally different keychain systems. The distinction matters for credential management. Legacy Login Keychain File on disk Password-based unlock upgrade to Modern Data Protection Keychain Secure Enclave backed Touch ID / biometric auth The login keychain is the legacy system. A file on disk (~/Library/Keychains/login.keychain-db), encrypted with your m