Where to store API keys on a Mac

In the Keychain, and handed to a command only when it runs. Not in a .env file in your project and not exported from your shell profile. If you want the same keys on more than one Mac, the keychain they're in matters too.

These are the five places developers usually keep API keys on a Mac. They expose keys in different ways, so here's what each one protects you from and what it doesn't.

1. A .env file in the project

The default for most frameworks, and the most exposed. The keys sit in plain text next to your code, where any tool or agent working in the project can read them. Coding agents like Claude Code, Codex and Gemini CLI read project files without asking, and Gemini CLI even loads .env into its own environment at startup.

dotenv's own README answers "Should I commit my .env file?" with "No." A .gitignore line handles that until the day someone copies the folder, zips it, or runs git add -f.

2. Exported in ~/.zshrc

This takes the keys out of the project, which helps. But export marks a variable for "the environment of subsequently executed commands", in the words of the zsh manual, so every program you start from a terminal gets every key: your editor, every script, every AI agent and everything those agents run.

The file is also plain text, and shell profiles are what people put in dotfiles repos. A study of 124,230 public dotfiles repositories found that 73.6% leaked potentially sensitive information, API keys among it.

3. The login keychain, with the security command

macOS ships a command-line tool for the Keychain. To store a key, put -w last so it prompts for the value instead of saving it in your shell history:

$ security add-generic-password -a "$USER" -s OPENAI_API_KEY -w

And to read it back in your own terminal when a command needs it, stopping if the lookup fails so the app doesn't start with an empty key:

(OPENAI_API_KEY=$(security find-generic-password -a "$USER" -s OPENAI_API_KEY -w) &&
  export OPENAI_API_KEY &&
  npm run dev)

The key is now encrypted at rest and only reaches the command you ran. That's a real improvement. There are three catches:

  • It doesn't sync. Apple's TN3137 explains that macOS has two keychains: the older file-based one and the data protection keychain. The security tool is "primarily focused on the file-based keychain", and iCloud Keychain needs the data protection one. A key you add this way stays on that Mac.
  • No grouping. Every key is a flat service name. Keeping a test STRIPE_KEY for one app and a live one for another means inventing naming schemes.
  • It's wordy. Five keys means five command substitutions in front of every command, which is why most people write a wrapper script around it.

envchain is a well-known wrapper that does exactly this: it stores named sets of variables in the Keychain and sets them only for the command you run. It uses the same older keychain API, so its items don't sync either. It has had one release since 2016 (v1.1.0, April 2024).

4. A password manager's CLI

If you already pay for 1Password, its CLI can run a command with secrets from your vault: op run replaces references in your environment with the real values and conceals them in output by default. Bitwarden has a CLI as well. Your keys sync wherever your password manager syncs, including other platforms.

The trade-off is setup and a subscription. You keep references like op://vault/item/field in a file for each project. 1Password Developer Environments adds a dedicated place for project variables if you'd rather skip the reference files.

5. iCloud Keychain, through an app built for it

The data protection keychain can sync through iCloud. Apple lists Passwords and Keychain as end-to-end encrypted even under Standard Data Protection: Apple doesn't have the encryption keys, and synced items "can't be decrypted by any other devices or by Apple", per its security guide.

The catch is that a third-party app has to opt each item into sync, and the security command can't do it for you. That's the gap fidelius fills. It's our Mac app that keeps API keys by project in your iCloud Keychain, so they reach every Mac signed in to your Apple ID, and it comes with accio to hand them to a command:

$ accio myapp npm run dev

STRIPE_KEY can be your test key in myapp and your live key in billing-api, and a shared project holds keys every project uses. Key files like a .p8 arrive as a temporary file that's deleted when the command ends.

Which one to pick

WhereEncrypted at restOut of project filesOnly reaches one commandSyncs across Macs
.env fileNoNoNoOnly if you copy it
~/.zshrc exportNoYesNoThrough dotfiles
security or envchainYesYesYesNo
1Password CLIYesYesYesYes
fideliusYesYesYesYes, through iCloud Keychain

On one Mac with a handful of keys, the security command is free and fine. It doesn't mask output, though, so a key your program prints reaches any agent that runs it. If you already live in 1Password, use op run. If you want keys grouped by project, synced between your Macs and set up for your coding agents, that's what we built fidelius for.