keychain

Check for a running ssh-agent, and start one if needed

$ keychain

$ keychain --agents "[gpg,ssh]"

$ keychain --list

$ keychain --list-fp

$ keychain --timeout [minutes]

keychain [options] [identity1 [identity2 ...]]

--clear, -c
    Clear all keys from existing agents before adding new ones.

--eval, -e
    Print shell commands suitable for eval to set agent variables.

--quiet, -q
    Suppress most output messages.

--help, -h
    Display help summary.

--version, -V
    Show version information.

--list, -l
    List fingerprints of keys currently managed.

--kill, -k [<ssh|gpg|all>]
    Terminate running agents (optionally specific ones).

--agents, -A <ssh[,gpg][,pgp]>
    Specify agents to manage (default: ssh,gpg).

--timeout, -t <minutes>
    Set default passphrase cache timeout.

--inherit [<local|any>]
    Allow child processes to inherit agent socket.

--quick
    Skip some safety checks for faster startup.

--nogui
    Do not use graphical pinentry programs.

Keychain is a user-friendly frontend to ssh-agent and ssh-add, simplifying the management of public key authentication credentials across shell sessions. It starts and maintains a single ssh-agent process per user login session, caching passphrases for SSH and GPG keys to avoid repeated entry.

Upon invocation, keychain checks for an existing agent; if none, it launches one and optionally loads specified identities. It outputs Bourne-shell commands to set environment variables like SSH_AUTH_SOCK and SSH_AGENT_PID, which users source in profiles like ~/.bash_profile or ~/.bashrc (e.g., eval `keychain --eval id_rsa`).

This enables persistent key access across logouts, new terminals, or su/sudo without re-prompting. Supports both SSH and GPG agents, with options for timeouts, inheritance, and clearing. Ideal for developers using Git, remote servers, or encrypted signing workflows.

Keychain handles host-specific state files (~/.keychain/*), ensuring compatibility across machines.

Keychain creates host-specific files in ~/.keychain/; mismatched hostnames may cause issues. Not suitable for multi-user or system-wide agents. Relies on Bourne-compatible shells for output.

Add to ~/.bash_profile:
eval `keychain --eval --agents ssh id_rsa id_ed25519`
This starts/uses agent and loads keys.

Run keychain --clear to remove keys, or keychain -k to kill agents entirely.

Originally written by Jay Dobies around 2001 as a bash script to streamline SSH key handling. Maintained and extended by the Linux community; current versions (2.8.x) add GPG support, timeout controls, and systemd integration.

ssh-agent(1), ssh-add(1), gpg-agent(1), ssh(1)