ssh-add

Add the default SSH keys in ~/.ssh to the ssh-agent

$ ssh-add

$ ssh-add [path/to/private_key]

$ ssh-add -l

$ ssh-add -d [path/to/private_key]

$ ssh-add -D

$ ssh-add -K [path/to/private_key]

ssh-add [options] [file ...]

file ...
    One or more private key files to add to the agent. If no files are specified, ssh-add attempts to add default identity files.

-A
    Adds all default identity files recursively from ~/.ssh/.

-a bind_address
    Specify the bind address for the smartcard socket.

-c
    Requests confirmation via ssh-askpass before adding or deleting keys from the agent.

-D
    Deletes all identities from the agent.

-d
    Deletes one specified identity from the agent. If no identity is specified, it prompts for which one to delete.

-E hash_algorithm
    Specifies the hash algorithm to use when displaying key fingerprints with -l or -L (e.g., md5 or sha256).

-F keyfile
    Specify a FIDO key to be registered.

-k
    Load a plain private key in PKCS#8 format (usually from a smartcard).

-K
    Adds the identity to the macOS keychain (macOS specific) in addition to the agent. The passphrase will be stored in the keychain.

-l
    Lists fingerprints of all identities currently loaded in the agent.

-L
    Lists public key parameters of all identities currently loaded in the agent.

-P
    Forces the addition of an identity with a non-empty passphrase without requiring the -c option for confirmation.

-p pin
    Provides the PIN for a smartcard (use with caution, as PIN might be visible in process listings).

-q
    Suppresses warning messages.

-R
    Adds an identity to the agent, requiring residency on the hardware token (e.g., FIDO device).

-r
    Registers a FIDO resident key, making it permanently available on the device.

-S
    Adds a smartcard identity.

-s seconds
    Sets a maximum lifetime for the smartcard identity in the agent. After this time, the identity is automatically removed.

-T seconds
    Sets the default lifetime for smartcard identities added without a specific -s option.

-t seconds
    Sets a maximum lifetime for the identity in the agent. After this time, the identity is automatically removed.

-u
    Unloads a FIDO resident key from the agent and optionally from the hardware token.

-v
    Enables verbose mode, printing debugging information.

-X
    Unlocks the agent, allowing identities to be added or removed. Used after -x.

-x
    Removes all identities from the agent and locks the agent. No further identities can be added or removed until unlocked with -X.

The ssh-add command adds private key identities (RSA, DSA, ECDSA, Ed25519, or FIDO) to the SSH authentication agent, ssh-agent.

When you connect to a remote server using SSH, your private key is used for authentication. If your private key is protected by a passphrase, you typically have to enter that passphrase every time you use the key. ssh-add simplifies this by loading your decrypted private keys into the agent's memory. Once added, the agent handles subsequent authentication requests without requiring repeated passphrase entries.

By default, ssh-add attempts to add common identity files such as ~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519, and ~/.ssh/id_xmss. You can also specify particular key files to add. Beyond adding keys, ssh-add provides options to list currently loaded identities, delete specific keys, or clear all keys from the agent, offering comprehensive management of your SSH authentication credentials.

For ssh-add to function, the ssh-agent daemon must be running and accessible. Identities added to the agent are typically session-specific and will be lost when the agent process terminates, unless explicitly saved (e.g., to the macOS keychain using -K). While convenient, storing decrypted keys in the agent's memory carries security implications; if your session is compromised, the keys in the agent could be exploited.

Without specifying file arguments, ssh-add will attempt to add the following default identity files from the ~/.ssh/ directory: id_rsa, id_dsa, id_ecdsa, id_ed25519, and id_xmss. If these files are passphrase-protected, you will be prompted for the passphrase for each one.

When adding a private key protected by a passphrase, ssh-add will prompt you to enter the passphrase. This passphrase is used to decrypt the key once, and the decrypted key is then stored in ssh-agent's memory. For subsequent SSH connections using that key, the agent handles the authentication without further passphrase prompts.

ssh-add communicates with ssh-agent via a Unix domain socket (or named pipe on Windows) specified by the SSH_AUTH_SOCK environment variable. This secure communication channel allows ssh-add to send commands to the agent (like 'add key' or 'list keys') and receive responses.

ssh-add is an integral part of the OpenSSH suite, a widely adopted tool for secure remote system access. Its development closely mirrors that of ssh-agent, aiming to enhance the usability of SSH by eliminating the need for repeated passphrase entry for private keys. Over time, it has evolved to support a variety of key algorithms including RSA, DSA, ECDSA, Ed25519, and more recently, FIDO hardware security keys, alongside features like key lifetime management and smartcard integration, reflecting the ongoing advancements in SSH security and convenience.

ssh-agent(1), ssh(1), ssh-keygen(1), ssh_config(5)