NAME
    keychain - Manager for ssh-agent, gpg-agent and private keys. Compatible
    with POSIX systems.

SYNOPSIS
    keychain [ -hklQqV ] [ --clear --confhost --confallhosts --debug
    --extended --gpg2 --help --ignore-missing --list --noask --nocolor --nog
    ui
    --noinherit --nolock --quick --quiet --ssh-allow-forwarded --ssh-allow-g
    pg
    --ssh-rm --ssh-spawn-gpg --systemd --version ] [ --ssh-agent-socket *pat
    h* ] [ --dir *dirname* ] [ --host *name* ] [ --lockwait *seconds* ]
    [ --stop *which* ] [ --timeout *minutes* ] [ --wipe *which* ] [ keys... 
    ]

INTRODUCTION
    Keychain helps you to manage SSH and GPG keys in a convenient and secure
    manner. It acts as a frontend to "ssh-agent" and "ssh-add", but allows
    you to easily have one long-running "ssh-agent" process per system,
    rather than the norm of one "ssh-agent" per login session.

    This dramatically reduces the number of times you need to enter your
    passphrase. With "keychain", you only need to enter a passphrase once
    every time your local machine is rebooted. Keychain also makes it easy
    for remote cron jobs to securely "hook in" to a long running "ssh-agent"
    process, allowing your scripts to take advantage of key-based logins.

    Keychain also supports GnuPG 2.1 and later, and will automatically start
    gpg-agent if any GPG keys are referenced on the command-line, and will
    ensure these credentials are cached in memory and available for use.

    Official project home: <https://github.com/danielrobbins/keychain>.

COMPATIBILITY
    Keychain supports most UNIX-like operating systems and intentionally
    limits its scope to modern, widely deployed implementations of OpenSSH
    and GnuPG.

    *   Minimum OpenSSH version: 7.3

        OpenSSH 7.3 (released 2016-08-01) introduced the "-G" (config dump)
        option used by Keychain to expand "host:" extended keys and the
        "--confallhosts" feature. Because this option is central to modern
        key discovery, Keychain officially targets OpenSSH 7.3 or newer.
        Earlier versions (>=6.5) may appear to work for basic usage (loading
        explicitly named keys) but are not part of the supported test
        matrix.

        Key types supported under the 7.3+ baseline include RSA, ECDSA and
        Ed25519 (Ed25519 first appeared in OpenSSH 6.5). DSA keys have been
        disabled by default upstream since OpenSSH 7.0; Keychain will still
        list or load them if they are explicitly enabled and present, but
        they are considered legacy.

        Features leveraged from OpenSSH:

            ssh -V            (implementation detection)
            ssh -nG host      (configuration expansion for host: extended keys)
            ssh-agent -s      (Bourne-compatible environment output; always forced)
            ssh-agent -t      (default key lifetime when spawning)
            ssh-agent -a path (explicit socket path when requested)
            ssh-add -l/-L     (list fingerprints / public keys)
            ssh-add -d/-D     (remove one / remove all keys)
            ssh-add -c        (confirmation mode)
            ssh-add -t        (per-key lifetime override)
            ssh-keygen -l -f  (fingerprint extraction, handles SHA256 & legacy MD5)
            Forwarded agent sockets (optionally adopted with --ssh-allow-forwarded)

    *   GnuPG / gpg-agent

        GnuPG 2.1 or later is required for gpg-agent integration. Keychain
        uses "gpg-connect-agent" "GETINFO socket_name" and "GETINFO
        ssh_socket_name" to detect, adopt or (optionally) spawn gpg-agent
        when acting as an SSH agent via "--ssh-allow-gpg" or
        "--ssh-spawn-gpg". Earlier GnuPG versions (2.0.x) lacked reliable
        SSH key storage support and are not supported.

    *   Shells

        The Keychain script itself requires a POSIX / Bourne-compatible
        shell. It generates pidfiles for Bourne ("...-sh"), csh/tcsh
        ("...-csh") and fish ("...-fish") shells. Internally Keychain now
        always consumes the canonical Bourne output of ssh-agent (forced
        with "-s") and derives the other shell formats. Bash, ksh and zsh
        consume the Bourne pidfiles.

        Keychain is officially supported on Git Bash (MSYS2) for Windows,
        including proper handling of Windows-style paths and usernames
        containing spaces.

        The csh/tcsh and fish pidfiles remain supported for backward
        compatibility. They are candidates for deprecation: a warning about
        planned removal will be announced at least two minor releases before
        any change.

    *   Spaces in HOME and paths

        Keychain 2.9.7+ properly handles home directories and private key
        paths containing spaces. All path variables in pidfiles
        (SSH_AUTH_SOCK) are quoted to ensure correct parsing by shells. The
        implementation uses a robust approach that evaluates ssh-agent
        output in a subshell to extract environment variables directly,
        rather than fragile string parsing. This ensures compatibility even
        if ssh-agent output format changes. File ownership detection uses
        POSIX-defined ls output format with logic to correctly parse
        usernames containing spaces.

    *   Legacy / Other SSH implementations

        SunSSH (found on older Oracle Solaris releases) may still function;
        code paths for SunSSH detection are retained but are not actively
        tested. They are scheduled for review and possible removal after
        three future minor releases unless community feedback requests
        retention.

        The historical commercial ssh.com implementation and its agent are
        no longer targets. If detected, behavior may fall back to simpler
        key loading; advanced features (confirmation, modern fingerprint
        parsing, host expansion) are not guaranteed. Reporting such usage
        via GitHub Issues will help shape any future support decisions.

    *   Systemd user environment

        On systems with systemd --user, Keychain can inject "SSH_AUTH_SOCK"
        (and optionally "SSH_AGENT_PID") via "--systemd" for wider session
        availability.

    Summary: A supported environment is OpenSSH >= 7.3 plus (optionally)
    GnuPG >= 2.1, running under any modern UNIX-like OS with a POSIX shell.
    Earlier versions or unlisted SSH implementations may work for basic
    scenarios but are outside official scope.

LIFECYCLE
    Typically, you configure keychain to run when you first log in to a
    system. If you are using Bourne shell or bash, you will create a
    ~/.profile or ~/.bash_profile file and include the following line in it:

        eval "$(keychain --eval id_rsa)"

    Keychain will start ssh-agent if one isn't already running. Keychain
    then checks to make sure your private keys (in this example, "id_rsa")
    are loaded into the agent. If they are not, you are prompted for any
    passphrase necessary to decrypt them, so that they are cached in memory
    and available for use.

    In addition to printing some user-friendly output to your terminal,
    keychain will also output important ssh-agent environment variables,
    which the "$( )" (you can also use "` `") captures, and the "eval"
    evaluates, setting these variables in your current shell.

    These ssh-agent environment variables are also written to
    ~/.keychain/${HOSTNAME}-sh, so that subsequent logins and
    non-interactive shells such as cron jobs can source the file to access
    the running ssh-agent and make passwordless ssh connections using the
    cached private keys -- even when you are logged out. These files are
    collectively called pidfiles.

    The key files specified on the command-line will be searched for in the
    ~/.ssh/ directory, and keychain will expect to find the private key file
    with the same name, as well as a ".pub" public key. Keychain will also
    see if any GPG keys are specified, and if so, prompt for any passphrases
    to cache these keys into "gpg-agent".

    Typically, private SSH key files are specified by filename only, without
    path, although it is possible to specify an absolute or relative path to
    the private key file as well. Private key files can be symlinks to the
    actual key as long as your system has the "readlink" command available.
    More advanced features are available for specifying keys as well -- see
    the --extended and --confallhosts options for more information.

    In addition, for GPG keys specified, similar steps will be taken to
    ensure that gpg-agent has the GPG key cached in memory and ready for
    use.

STREAMLINING AND SIMPLIFICATION
    Keychain 2.9.0 has been streamlined, and with this maintenance several
    command-line options have been retired as they are not completely
    necessary. This simplifies the use of the tool by making it more
    intuitive to use. The files created in ~/.keychain have also been
    cleaned up. This section details all the important changes.

  PIDFILE CHANGES
    "Pidfile" is the nickname for files created in ~/.keychain which can
    then be sourced by your scripts to access a running agent.

    When using gpg-agent for GPG keys, keychain will no longer create a
    ~/.keychain/${HOSTNAME}-sh-gpg pidfile. This file is no longer needed as
    the canonical GPG socket inside ~/.gnupg/ will be used to detect the
    running gpg-agent, which is the modern convention. GnuPG 2.1 and later
    have stopped using environment variables to find the agent, so we follow
    this upstream change.

  IMPROVED DEBUGGING
    A new --debug option is now available which will print additional
    information related to keychain's decisions regarding why and how an
    agent was found -- or not.

  NEW (AND DEPRECATED) OPTIONS
    This section provides an overview of new and deprecated command-line
    options. For full details on each option, see the respective option
    definition under "OPTIONS".

   Keychain 2.9.2
    The "--confhost" option has been deprecated. Instead of "--confhost
    hostname", use "--extended host:hostname". This extended format allows
    multiple keys of multiple types (SSH, GPG and SSH-from-hostname) to be
    specified on the command-line together. This is also fully compatible
    with "--confallhosts", and keychain now de-duplicates the list of keys
    to be loaded.

   Keychain 2.9.1
    The short-lived "--ssh-wipe" and "--gpg-wipe" options that appeared only
    in version 2.9.0 were replaced with "--wipe *which*" to work similarly
    to the "--stop" option, and allows you to specify "ssh", "gpg" or "all".

   Keychain 2.9.0
    The "--agents" option is now deprecated. Keychain will always ensure an
    ssh-agent or equivalent is running, or if "--ssh-spawn-gpg" is used,
    potentially a gpg-agent for the purpose of storing SSH keys if no
    running ssh-agent is available. To simply use a gpg-agent if one is
    already running, falling back to launching ssh-agent if no agent is
    available, use the "--ssh-allow-gpg" option.

    Specifying a GPG key on the command-line will instruct keychain to
    enable gpg-agent functionality automatically. This eliminates an option
    that you need to specify ("--agents ssh,gpg") when invoking keychain,
    and for many will avoid spawning a GPG agent you may not be using.

    Specifying the "--agents" option will now display a warning that it's
    deprecated, but keychain will not abort.

    The "--inherit" option, which took one of four arguments, has been
    deprecated. Keychain's default behavior remains that of preferring to
    use an ssh-agent or equivalent referenced by its pidfile, falling back
    to finding an ssh-agent in its environment. By default, keychain will
    not use a gpg-agent socket for SSH keys unless at least
    "--ssh-allow-gpg" is specified. Similarly, the use of any forwarded SSH
    agent connection is disabled by default and can be enabled via
    "--ssh-allow-forwarded". Again, see the full documentation for each
    option in the "OPTIONS" section.

    You can still influence keychain's behavior via the still-present
    "--noinherit" option which will prevent all detection of existing SSH
    agents via the environment.

    The "--clear" option is still available, but isn't intended to be a
    "standalone" option, meaning that it is used to perform an initial
    clearing of cached keys before loading any specified keys when Keychain
    is run. To perform the sole action of wiping all cached keys, use the
    "--wipe" action. To remove an individual cached SSH private key or keys,
    use the "--ssh-rm" *keyfile* option.

    The "--stop" option will now only stop any running ssh-agent processes,
    and still supports three possible options: "mine", "others" and "all".
    It no longer stops gpg-agent processes, which tend to get auto-respawned
    by GPG tools, so killing gpg-agent typically doesn't make a lot of
    sense.

  BETTER GNUPG INTEGRATION
    Keychain can now use an existing gpg-agent that has been started in your
    environment to store ssh keys, rather than spawning its own ssh-agent,
    by using the "--ssh-allow-gpg" option.

    If you would like keychain to spawn gpg-agent instead of ssh-agent, and
    use it to store SSH keys, specify the "--ssh-spawn-gpg" option.

    Without either option, keychain will not use an SSH_AUTH_SOCK that is
    provided by gpg-agent, and will spawn an official ssh-agent process.

    In addition, behind the scenes, keychain now uses the gpg-connect-agent
    executable to restart the agent, get official PID and socket
    information, etc.

    Please note that while gpg-agent provides full compatibility with
    ssh-agent, its password prompt is handled by pinentry and its store may
    encrypt your in-memory keys. For this reason, consider this new feature
    experimental, and use GitHub issues to report back any anomalies or
    suggested improvements for gpg-agent integration.

  DISPLAY CHANGES
    When keychain uses gpg-agent for either GnuPG or SSH support, then
    keychain will display the GnuPG socket file in its output, rather than
    the PID. Since the socket file has the ~/.gnupg path in it, this
    communicates to you that gpg-agent, not ssh-agent, is active. If you see
    an integer PID, this means that ssh-agent is being used.

  STREAMLINED STARTUP
    By default, keychain will always ensure that an ssh-agent should be
    started. It will only start a gpg-agent if a GPG key is referenced on
    the command-line.

    Modern versions of gpg-agent also support the caching of SSH keys,
    allowing it to be a drop-in replacement for ssh-agent. With keychain
    2.9.0, a new "--ssh-spawn-gpg" option has been added, which when
    specified will give keychain permission to spawn a gpg-agent in place of
    ssh-agent.

  CODE OPTIMIZATION
    With keychain 2.9.0, there has been significant code cleanup, reducing
    the size of the script from 1500 lines to about 1100 lines. In addition,
    the script is now fully compliant with ShellCheck
    <https://shellcheck.net>, which will be hugely helpful to ensure
    continued POSIX shell compatibility moving forward.

AGENT DETECTION AND STARTUP ALGORITHM
    This section documents the official algorithm used for detecting and if
    necessary starting ssh-agent, to facilitate understanding as well as
    developer maintenance of the codebase.

  DEFINITIONS
    There are several important definition related to the algorithm:

    1. The agent, "ssh-agent", which is a long-running daemon. This can also
    in some cases be "gpg-agent", depending on command-line options.
    2. The inherited agent, which is the agent or forwarded agent that was
    not started by keychain, but is detected in the environment or by other
    means.
    3. The adopted agent, which is an inherited agent whose information has
    been persisted by being written to the pidfiles (see below).
    4. The environment variables "SSH_AUTH_SOCK", which points to the socket
    file used to communicate with ssh-agent, and optionally "SSH_AGENT_PID",
    which indicates its process ID if running locally (although gpg-agent
    does not define "SSH_AGENT_PID", even if running locally.)
    5. The file ~/.keychain/${HOSTNAME}-sh and related files, which are
    collectively referred to as "pidfiles". Pidfiles are used to
    persistently store "SSH_AUTH_SOCK" and "SSH_AGENT_PID" environment
    variables for use by other scripts, as well as by keychain itself,
    formatted so that they can be "sourced" by shells of various types.
    6. Relevant command-line options affecting behavior, which include
    --noinherit, --ssh-allow-gpg, --ssh-spawn-gpg, and
    --ssh-allow-forwarded.

  ALGORITHM OVERVIEW
    When the keychain script is run, it will first attempt to find a running
    ssh-agent.

    Phase 1: pidfile: To do this, it will first look for an existing
    pidfile. If one exists, it will be inspected and used to find a running
    agent, in alignment with specified command-line options. If this process
    is successful, a "keychain-spawned" agent is found and this process is
    complete. Otherwise, we continue to the next step.
    Phase 2: environment: If keychain's pidfile did not yield a running
    agent, keychain looks at environment variables defined in the current
    environment. This step will be skipped if the --noinherit option is
    specified. If an agent is found that is in alignment with specified
    command-line options, it is considered "inherited" by keychain, and the
    process is complete. Otherwise, we continue to the next step.
    Phase 3: spawn agent: In the absence of finding a keychain-spawned or
    existing agent that can be adopted, keychain will spawn a new ssh-agent,
    or a new gpg-agent if --ssh-spawn-gpg is specified and gpg-agent is
    available.
    Final Phase: update pidfile: In addition, the pidfiles will be updated
    to reflect the keychain-spawned or "inherited" agent. An "inherited"
    agent, once written to the pidfile, is now considered to be "adopted".
    Pidfile update exception: If the --ssh-allow-forwarded option was
    specified, and a forwarded SSH socket was found -- which is identified
    as a valid SSH socket defined in a "SSH_AUTH_SOCK" variable, which has
    no associated or valid "SSH_AGENT_PID" also defined in the environment
    and is also determined to not be the socket of any running gpg-agent --
    then this agent will simply be used, but not persisted in any pidfile.
    This is because this SSH-supplied socket will disappear when the
    underlying SSH connection terminates, and thus it cannot be relied on to
    be available persistently.

  THE QUICK SHORT-CIRCUIT
    When the --quick option is specified, a special algorithm will run prior
    to the main agent-detection algorithm listed above. A pidfile, if it
    exists, will be evaluated as per Phase 1 of the main algorithm. If a
    valid running agent is found, it will be queried for valid keys. If at
    least one valid key is loaded into the agent, the quick start is
    considered successful, and keychain will skip the regular agent startup
    algorithm, and will use this found agent.

  SUMMARY AND RATIONALE
    The keychain ssh-agent detection and startup algorithm is somewhat
    sophisticated for a reason. There is an intention behind its behavior.

    The algorithm has been specifically designed to prefer an agent spawned
    by keychain, or previously adopted, if that agent is currently
    available. This is by design, because other system software could spawn
    ssh-agent and/or gpg-agent processes, and we want keychain to not
    coerced into using these new agents which may suddenly appear in the
    environment unexpectedly when new desktop sessions start and in other
    circumstances. If keychain is too "suggestible", it will lose track of
    the agent which currently holds valid keys, which can result in
    unnecessary prompting for passphrases, and general confusion.

OPTIONS
    --absolute
        This option can be used with the --dir option, if you would like to
        specify a non-default directory to store pidfiles (defaults to
        ~/.keychain). When this option is used, the script does not
        automatically append /.keychain to the path, allowing you to use any
        arbitrary directory name for the storing of pidfiles. Please note
        that Keychain 2.9.3 adds some extra security checks related to
        directory and file permissions -- you must have exclusive ownership
        of any directory that keychain uses to store pidfiles, or keychain
        will abort.

    --clear
        When specified, this option adds an initial step prior to adding any
        keys to the agents of wiping all existing cached keys/passphrases.
        This is intended to be used alongside keychain --eval to ensure that
        only the specified keys are loaded, and that keychain should assume
        that you are an intruder until proven otherwise and force all
        interactive logins to specify valid passphrases. This option
        increases security and still allows your cron jobs to use your ssh
        keys when you're logged out.

    --confallhosts
        In addition to any keys specified on the command-line, this option
        will tell keychain to scour ~/.ssh/config for all private keys
        referenced in all "IdentityFile" lines, and load all keys for all
        hosts.

    --confirm
        Keys are subject to interactive confirmation by the SSH_ASKPASS
        program before being used for authentication. See the -c option for
        ssh-add(1).

    --debug
        Keychain 2.9.0 introduces the --debug option, which will output
        additional information related to how Keychain makes its
        agent-selection process. Specifically, it will output when an
        SSH_AUTH_SOCK is rejected because it is being supplied by gpg-agent
        -- and this is not allowed due to no --ssh-allow-gpg option, or when
        it is rejected because it appears to be from a forwarded SSH
        connection, and --ssh-allow-forwarded was not supplied.

    --dir *dirname*
        This option allows you to use another directory besides
        $HOME/.keychain for the storing of pidfiles. Please note that
        Keychain 2.9.3 adds some extra security checks related to directory
        and file permissions -- you must have exclusive ownership of any
        directory that keychain uses to store pidfiles, or the script will
        abort. Also see the --absolute option.

    --env *filename*
        After parsing options, keychain will load additional environment
        settings from "filename". By default, if "--env" is not given, then
        keychain will attempt to load from ~/.keychain/[hostname]-env or
        alternatively ~/.keychain/env. The purpose of this file is to
        override settings such as PATH, in case ssh is stored in a
        non-standard place.

    --eval
        Keychain will print lines to be evaluated in the shell on stdout. It
        respects the SHELL environment variable to determine if Bourne shell
        or C shell output is expected.

    --extended
        This enables extended command-line key processing with more
        features, and is a replacement for the old "--confhost" option. When
        specified, each key specified on the command-line must have a prefix
        to explicitly categorize it. SSH keys must have a prefix of "sshk:"
        immediately followed by the path or key name (the part after the
        "sshk:" is processed just like a SSH key is without the "--extended"
        option). GPG keys must be in the format "gpgk:" immediately followed
        by the 8 or 16-character fingerprint. If "host:<hostname>" is
        specified, then Keychain will extract the SSH configuration for the
        specified hostname, grab all identityfile options (private keys)
        specified, and these keys will be included in the set of keys to be
        loaded by keychain. This allows multiple keys of multiple types,
        including SSH-keys-by-host, to be specified together, which wasn't
        possible with "--confhost".

    --gpg2
        This option changes the default gpg calls to use gpg2 instead to
        support distributions such as Ubuntu which has both gpg and gpg2

    -h --help
        Show help that looks remarkably like this man-page. As of 2.6.10,
        help is sent to stdout so it can be easily piped to a pager.

    --host *name*
        Set alternate hostname for creation of pidfiles

    --ignore-missing
        Don't warn if some keys on the command-line can't be found. This is
        useful for situations where you have a shared .bash_profile, but
        your keys might not be available on every machine where keychain is
        run.

    -l --list
        List signatures of all active SSH keys, and exit, similar to
        "ssh-add -l".

    -L --list-fp
        List fingerprints of all active SSH keys, and exit, similar to
        "ssh-add -L".

    --lockwait *seconds*
        How long to wait for the lock to become available. Defaults to 5
        seconds. Specify a value of zero or more. If the lock cannot be
        acquired within the specified number of seconds, then this keychain
        process will forcefully acquire the lock.

    --noask
        This option tells keychain do everything it normally does (ensure
        ssh-agent is running, set up the ~/.keychain/[hostname]-{c}sh files)
        except that it will not prompt you to add any of the keys you
        specified if they haven't yet been added to ssh-agent.

    --nocolor
        Disable color highlighting for non ANSI-compatible terms.

    --nogui
        Don't honor SSH_ASKPASS, if it is set. This will cause ssh-add to
        prompt on the terminal instead of using a graphical program.

    --noinherit
        Don't inherit any agent processes, overriding the default behavior
        of inheriting all non-forwarded ssh-agent and any existing gpg-agent
        processes. Also see "AGENT DETECTION AND STARTUP ALGORITHM".

    --nolock
        Don't attempt to use a lockfile while manipulating files, pids and
        keys.

    --query
        Keychain will print lines in KEY=value format representing the
        values which are set by the agents.

    -Q --quick
        If an ssh-agent process is running then use it. Don't verify the
        list of keys, other than making sure it's non-empty. This option
        avoids locking when possible so that multiple terminals can be
        opened simultaneously without waiting on each other. See the "THE
        QUICK SHORT-CIRCUIT" section for more information regarding how this
        fits into the overall startup algorithm.

    -q --quiet
        Only print messages in case of warning, error or required
        interactivity. As of version 2.6.10, this also suppresses
        "Identities added" messages for ssh-agent.

    -k --stop *which*
        Kill currently running ssh-agent processes and exit.

        Note that previous versions of keychain (2.8.5 and earlier) allowed
        killing of gpg-agent as well. This functionality was removed as
        ssh-agent and gpg-agent have a bit different design philosophies and
        you almost always only have at most one gpg-agent running at a time.
        Use "killall gpg-agent" if you really want to kill gpg-agent.
        However, since this option also removes pidfiles, it will remove any
        gpg-agent processes adopted by keychain that were being used to
        store ssh keys.

        The following values are valid for "which" which controls which
        ssh-agents to target:

        all      Kill all ssh-agent processes and quit keychain immediately.
                 Prior to keychain-2.5.0, this was the behavior of the bare
                 "--stop" option.

        others   Kill agent processes other than the ones keychain is
                 providing. Prior to keychain-2.5.0, keychain would do this
                 automatically. The new behavior requires that you specify
                 it explicitly if you want it.

        mine     Kill keychain's agent processes, leaving other agents
                 alone.

    --ssh-agent-socket *path*
        Use this option to specify the path to the socket file that you
        would like ssh-agent to create and use as its official socket. By
        default, ssh-agent will create its own socket file, typically in
        /tmp.

    --ssh-allow-forwarded
        By default, keychain will not use a forwarded ssh-agent connection,
        which is a ssh-agent socket created by SSH that has no associated
        local process. To permit keychain to use a forwarded ssh-agent
        connection, specify this option. If a SSH-forwarded socket is used,
        it will not be persisted in the pidfiles, as it is not likely to be
        available outside of the currently-active SSH session.

    --ssh-allow-gpg
        Would you like to have keychain use an already-running gpg-agent to
        store your SSH keys, rather than spawning a new ssh-agent? This
        option does just that. When this option is specified, keychain will
        accept an SSH_AUTH_SOCK environment variable in its environment,
        even if it was created by gpg-agent. Modern versions of gpg-agent
        are also able to store SSH keys. By default, keychain has a special
        check to avoid using a gpg-agent that has set the SSH_AUTH_SOCK
        environment variable, and will instead spawn its own ssh-agent. With
        this option enabled, this restriction is turned off. Please note
        that this option does not actually instruct keychain to *spawn* a
        gpg-agent for storing SSH keys if no agent is available -- if you
        want that, see the --ssh-spawn-gpg option, below.

        ALSO NOTE: When a gpg-agent is adopted for ssh-agent duties in this
        way, the ~/.keychain/${HOSTNAME}-sh pidfile will be updated to
        reference the gpg-agent socket, so it will be seamlessly used by
        future cron jobs needing an ssh-agent, as well as by future
        invocations of keychain, as long as the --ssh-allow-gpg or
        --ssh-spawn-gpg (which implies --ssh-allow-gpg) are specified.

    --ssh-spawn-gpg
        This is the option to use if you're really on-board with using
        gpg-agent as a replacement for ssh-agent. Not only will keychain use
        a running gpg-agent if found as per the --ssh-allow-gpg, but if it
        needs to spawn a new ssh-agent, it will go ahead and spawn a
        gpg-agent in its place, and use it instead. Also see notes for the
        --ssh-allow-gpg option, as this option also implies --ssh-allow-gpg.

    --ssh-rm -r *keys*
        Only perform the single action of removing the specified cached keys
        from the running ssh-agent, and then exit.

    --systemd
        Inject environment variables into the systemd --user session.

    --timeout *minutes*
        Allows a timeout to be set for identities added to ssh-agent. When
        this option is used with a keychain invocation that starts ssh-agent
        itself, then keychain uses the appropriate ssh-agent option to set
        the default timeout for ssh-agent. The --timeout option also gets
        passed to ssh-add invocations, so any keys added to a running
        ssh-agent will be individually configured to have the timeout
        specified, overriding any ssh-agent default.

        Most users can simply use the timeout setting they desire and get
        the result they want -- with all identities having the specified
        timeout, whether added by keychain or not. More advanced users can
        use one invocation of keychain to set the default timeout, and
        optionally set different timeouts for keys added by using a
        subsequent invocation of keychain.

    -V --version
        Show version information.

    --wipe *which*
        Only perform the single action of wiping all agent's cached keys.
        Specify 'ssh', 'gpg' or 'all' for SSH keys, GPG keys and all agents
        respectively. Also see the "--ssh-rm" action and the "--clear"
        option.

EXAMPLES
    This snippet should work in most shells to load two ssh keys and one gpg
    key:

        eval `keychain --eval id_rsa id_dsa 0123ABCD`

    For the fish shell, use the following format:

        if status --is-interactive
            keychain --eval --quiet -Q id_rsa | source
        end

    If you have trouble with that in csh:

        setenv SHELL /bin/csh
        eval `keychain --eval id_rsa id_dsa 0123ABCD`

    This is equivalent for Bourne shells (including bash and zsh) but
    doesn't use keychain's --eval feature:

        keychain id_rsa id_dsa 0123ABCD
        [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
        [ -f $HOME/.keychain/$HOSTNAME-sh ] && \
                . $HOME/.keychain/$HOSTNAME-sh

    This is equivalent for C shell (including tcsh):

        keychain id_rsa id_dsa 0123ABCD
        host=`uname -n`
        if (-f $HOME/.keychain/$host-csh) then
                source $HOME/.keychain/$host-csh
        endif

    Likewise, the following commands can be used in fish:

        keychain id_rsa id_dsa 0123ABCD
        test -z "$hostname"; and set hostname (uname -n)
        if test -f "$HOME/.keychain/$hostname-fish"
            source $HOME/.keychain/$hostname-fish
        end

    To load keychain variables from a script (for example from cron) and
    abort unless id_dsa is available:

        # Load keychain variables and check for id_dsa
        [ -z "$HOSTNAME" ] && HOSTNAME=`uname -n`
        . $HOME/.keychain/$HOSTNAME-sh 2>/dev/null
        ssh-add -l 2>/dev/null | grep -q id_dsa || exit 1

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

NOTES
    Keychain was created and is currently maintained by Daniel Robbins. To
    report a bug or request an enhancement, use the issue tracker at
    <https://github.com/danielrobbins/keychain>.

    Keychain includes bash completion support for command-line options, SSH
    keys, GPG keys, and extended mode prefixes ("sshk:", "gpgk:", "host:").
    The completion script is included in the source tarball at
    "completions/keychain.bash". For installation instructions, see the
    README file or run "make install-completions".

    The former Funtoo Linux wiki page is preserved only as an historical
    reference: <https://www.funtoo.org/Funtoo:Keychain>.

