__ _______________________ _________._________________________ \_ _____/ \______ \ / _ \ / _____/ / _____/ | | \_ _____/ | __) | _/ / /_\ \ / \ ___ / \ ___ | | | __)_ | \ | | \ / | \ \ \_\ \ \ \_\ \ | |___ | \ \___ / |____|_ / \____|__ / \______ / \______ / |_______ \ /_______ / \/ \/ \/ \/ \/ \/ \/

gpg-agent Cheatsheet

← Back to cheatsheets

← Home

gpg-agent is a daemon that manages GPG private keys and passphrases. It caches passphrases so you don't have to enter them repeatedly, and can use hardware tokens or pinentry programs for secure passphrase entry.

Basic Usage

  • gpg-agent --daemon - Start the agent daemon
  • gpg-agent --kill - Stop the agent
  • gpg-agent --version - Show version

Configuration

  • ~/.gnupg/gpg-agent.conf - Main configuration file
  • default-cache-ttl 600 - Cache passphrase for 10 minutes
  • max-cache-ttl 7200 - Maximum cache time (2 hours)
  • pinentry-program /usr/bin/pinentry - Specify pinentry program
  • enable-ssh-support - Enable SSH agent emulation

SSH Agent Emulation

  • enable-ssh-support in gpg-agent.conf - Enable SSH support
  • ssh-add -l - List SSH keys (when using gpg-agent)
  • export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) - Set SSH socket
  • Add to ~/.bashrc or ~/.zshrc for persistent SSH support

Reload Configuration

  • gpgconf --kill gpg-agent - Kill agent
  • gpgconf --launch gpg-agent - Restart agent
  • gpg-connect-agent reloadagent /bye - Reload without restart

Common Examples

Start Agent

eval $(gpg-agent --daemon)

Start agent and set environment variables.

Check Agent Status

gpg-connect-agent /bye

Test if agent is running.

Clear Passphrase Cache

gpg-connect-agent reloadagent /bye

Clear cached passphrases.

SSH Support Setup

echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent
eval $(gpg-agent --daemon)

Enable SSH agent emulation.

Tips

  • gpg-agent usually starts automatically when needed
  • Use pinentry for secure passphrase entry (GUI or TTY)
  • Set reasonable cache TTLs for security vs convenience
  • SSH agent emulation lets you use GPG keys for SSH
  • gpgconf is the modern way to manage gpg-agent