How to Fix 'ssh-add: illegal option -- K' on macOS Monterey through Sequoia

The 2 AM Authentication Fail

You just finished a long coding session and you're ready to push your work. You type your usual command to load your SSH key into the macOS Keychain: ssh-add -K ~/.ssh/id_ed25519. But instead of the usual success message, your terminal hits you with a wall of text.

ssh-add: illegal option -- K
usage: ssh-add [-cDlLqXx] [-t life] [file ...]
       ssh-add -s pkcs11
       ssh-add -e pkcs11

It worked yesterday. It worked on your old MacBook. But on macOS Monterey or newer, your muscle memory is now throwing errors. This happens because Apple changed how their custom SSH flags work to stay compatible with standard OpenSSH.

What changed in macOS?

Apple updated the built-in OpenSSH version to 8.6p1 starting with macOS Monterey (12.0). Before this update, Apple used a custom patch that added the -K and -A flags. These were non-standard shortcuts used specifically to talk to the macOS Keychain.

To align with modern OpenSSH standards, Apple renamed these flags. The old -K is now --apple-use-keychain, and -A is now --apple-load-keychain. If you try to use the old single-letter versions, the updated binary simply won't recognize them. It's a minor change, but it breaks years of habit for many developers.

The Quick Fix (Manual Command)

If you need to push your code right now, just use the long-form flag. Swap -K for the new, descriptive version:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Note: If you use an older RSA key, replace id_ed25519 with id_rsa.

Similarly, if you usually run ssh-add -A after a reboot to pull all your keys back into the agent, use this instead:

ssh-add --apple-load-keychain

The Permanent Fix (SSH Config)

Running manual commands every time you restart your terminal is a waste of time. A better approach is to update your SSH configuration. This tells macOS to look in the Keychain automatically whenever you try to connect to a server.

1. Open your SSH config file with nano or your favorite editor:

nano ~/.ssh/config

2. Paste in these lines. This configuration ensures SSH handles the Keychain and agent management for you:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

What these lines actually do:

• AddKeysToAgent yes: This automatically loads your key into the ssh-agent the very first time you use it. No more manual ssh-add.
• UseKeychain yes: This is the macOS-specific secret sauce. It tells the system to store and retrieve your passphrase from the macOS Keychain.
• IdentityFile: This points to your specific key. If you have multiple keys for different jobs, you can add multiple IdentityFile lines here.

3. Save and exit (Press Ctrl+O, Enter, then Ctrl+X).

Testing the Setup

Let's make sure everything is working as expected. First, clear your current session by killing the active agent:

killall ssh-agent

Now, try to connect to GitHub:

ssh -T git@github.com

If your config is correct, a macOS dialog box will pop up asking for your SSH passphrase. Make sure you check the box that says "Remember password in my keychain." Once you do this once, you'll never have to type it again.

Common Gotchas

Strict Permissions: SSH will ignore your config file if the permissions are too broad. Security is tight here. Ensure your .ssh folder and the config file have the correct ownership:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config

Old Shell Aliases: Check your .zshrc or .bash_profile. If you have an old alias like alias sload='ssh-add -K', it will still fail. Update those aliases to use the --apple-use-keychain flag or delete them entirely now that your config file handles the heavy lifting.