Overview
ssh-add gives your private keys to a running ssh-agent, so that you type the passphrase of a key once instead of each time you connect. With -l it lists the keys the agent holds, with -L it prints their public keys and with -D it removes them all. It needs a running agent: without one it reports that it cannot connect. This page also answers for sshadd, a common misspelling; the real command has a hyphen.
Background
ssh-add is part of OpenSSH, whose manual is on man.openbsd.org. The tool tested here is the OpenSSH that macOS ships. The examples that start their own agent use a short socket path in /tmp, because the path of a long temporary folder is too long for a Unix socket.
Examples
Without an agent, ssh-add -l cannot connect and the status is 2:
env -u SSH_AUTH_SOCK ssh-add -l > /dev/null 2>&1; echo "status $?"
Start a private agent, add a throw-away key, and count the keys in the list; the agent stops with the command, and the socket file is removed:
ssh-keygen -q -t ed25519 -N '' -f k && ssh-agent -a "/tmp/sa$$" sh -c 'ssh-add k 2> /dev/null && ssh-add -l | wc -l | tr -d " "'; rm -f "/tmp/sa$$"
Print the public key of the added key; the first field is its type:
ssh-keygen -q -t ed25519 -N '' -f k && ssh-agent -a "/tmp/sa$$" sh -c 'ssh-add k 2> /dev/null; ssh-add -L | cut -d" " -f1'; rm -f "/tmp/sa$$"
Remove all keys again with -D; the list is then empty and the status is 1:
ssh-keygen -q -t ed25519 -N '' -f k && ssh-agent -a "/tmp/sa$$" sh -c 'ssh-add k 2> /dev/null; ssh-add -D 2> /dev/null; ssh-add -l > /dev/null 2>&1; echo "status $?"'; rm -f "/tmp/sa$$"
Options
-l
List the fingerprints of the keys in the agent.
-L
Print the public keys held by the agent.
-D
Remove all keys from the agent.
-d
Remove one key.
Common mistakes
An agent holds your key in memory and anyone who can use the agent's socket can use your key, so do not forward an agent (ssh -A) to a host you do not trust. ssh-add with no arguments adds the default keys, such as ~/.ssh/id_ed25519, and asks for a passphrase on a terminal. A key with the wrong permissions is refused. On macOS, --apple-use-keychain stores the passphrase in the keychain, and that option does not exist in other versions.
Portability
The options above are the same in OpenSSH on every system, and the status values are 0 (keys listed), 1 (no keys) and 2 (no agent). The examples were executed on the OpenSSH of the macOS host. The Common examples were executed on OpenSSH (the macOS system build) (see the development guide for the exact check).
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.