GnuPG Cheatsheet - GPG Encrypt, Sign & Key Management

Everyday GPG collapses into four actions: generate a keypair, hand your public key over, let the other side encrypt with it, and decrypt or sign with your private key. What actually breaks is rarely the commands and almost always the key material, since a lost private key is unrecoverable and an unverified imported key may have been swapped in transit. So the first habit after generation is to export a backup, and the first habit after import is to check the fingerprint against a channel you trust. This sheet walks the full chain through key generation and management, import and export, encryption and decryption, signing and verification, trust and key servers, and Git signing. Two more habits pay off repeatedly: pass --armor for text-safe output you can paste into an email, and rely on gpg-agent to cache the passphrase so you are not retyping it for every message. Pinning the fingerprint through trustedchannels is what upgrades an imported key from merely present to genuinely trusted.

SysOps·37 commands·Last updated 2026-07-21

Typical Use Case

For engineers who need verifiable identity rather than trust-by-fiat: signing Git commits and tags, encrypting files for a teammate, verifying a downloaded release. GnuPG is older than most people expect and its failure modes are specific: a missing gpg-agent, a key whose trust was never set, a key server that silently serves nothing. This sheet covers key lifecycle, import/export, encryption, both signature styles, and commit signing.

Key Generation 8

gpg --full-generate-key

Interactive key pair generation

gpg --quick-generate-key "Name <email>"

Quick key generation

gpg --list-keys

List all public keys

gpg --list-secret-keys

List all secret keys

gpg --list-keys KEYID

Show a key's details

gpg --edit-key KEYID

Edit a key interactively

gpg --delete-key KEYID

Delete a public key

gpg --delete-secret-key KEYID

Delete a secret key

Import & Export 6

gpg --export -a KEYID > pubkey.asc

Export a public key to ASCII

gpg --export-secret-keys -a KEYID > private.asc

Export a secret key (keep it safe)

gpg --import pubkey.asc

Import a public key

gpg --import private.asc

Import a secret key

gpg --send-keys KEYID --keyserver keyserver.ubuntu.com

Upload a public key to a keyserver

gpg --recv-keys KEYID

Fetch a public key from a keyserver

Encrypt & Decrypt 6

gpg -e -r recipient@domain.com secret.txt

Encrypt a file with a recipient's public key

gpg -e -r user@domain.com -o secret.txt.gpg secret.txt

Encrypt and set the output filename

gpg -d secret.txt.gpg > secret.txt

Decrypt to a file

gpg -c secret.txt

Symmetric encryption (password only)

gpg -d secret.txt.gpg

Decrypt a symmetric file

echo "message" | gpg -e -r user@domain.com

Encrypt piped text

Sign & Verify 6

gpg -s document.txt

Create a signature (.gpg binary)

gpg --clear-sign document.txt

Create a clear-text signature

gpg -b document.txt

Create a detached signature (.sig)

gpg --verify document.txt.sig document.txt

Verify a detached signature

gpg --verify document.txt.asc

Verify a clear-text signature file

gpg --detach-sign -a file.tar.gz

Create an ASCII detached signature

Trust & Keyserver 5

gpg --edit-key KEYID\n> trust

Set a key's trust level (interactive)

gpg --sign-key KEYID

Sign someone's public key (endorsement)

gpg --refresh-keys

Refresh all keys from the keyserver

gpg --search-keys "user@domain.com"

Search the keyserver for a key

gpg --fingerprint KEYID

Show a key fingerprint to verify identity

Git Signing 6

git config --global user.signingkey KEYID

Set the signing key for Git

git config --global commit.gpgsign true

Auto-sign all commits

git commit -S -m "message"

Create a GPG-signed commit

git tag -s v1.0 -m "release"

Create a GPG-signed tag

git verify-commit HEAD

Verify the latest commit's signature

gpgconf --kill gpg-agent

Restart gpg-agent (fix passphrase cache)

Parameter matrix

Parameter	Effect	Example
`--quick-generate-key`	Non-interactive key creation in one command, the scripted alternative to --full-generate-key	`gpg --quick-generate-key "Name <email>"`
`--recv-keys`	Fetch someone's public key from a keyserver; needs a key ID or email, and a typo fails silently	`gpg --recv-keys KEYID`
`--clear-sign`	Produce a cleartext signature: readable text with the signature embedded	`gpg --clear-sign document.txt`
`commit.gpgsign`	Make every git commit GPG-signed automatically so verifiers can trace the key fingerprint	`git config --global commit.gpgsign true`
`gpgconf --kill gpg-agent`	Restart the agent to clear stale passphrase state after changing a password	`gpgconf --kill gpg-agent`

Common pitfalls

SymptomAfter gpg --import, gpg --verify still refuses the signature or prints a WARNING.

CauseThe key is imported but untrusted; gpg has no basis for considering it legitimate.

FixCheck gpg --fingerprint KEYID first, then gpg --edit-key KEYID and set trust to ultimate, and verify again.

Symptomgpg --recv-keys finishes silently but the key never appears locally.

CauseThe email is mistyped or the keyserver simply has no such key, so the response is empty.

FixRun gpg --search-keys "user@domain.com" to find the exact key ID, then gpg --recv-keys.

SymptomAfter changing the passphrase, gpg still accepts the old one or hangs.

Causegpg-agent holds stale passphrase state.

FixRun gpgconf --kill gpg-agent to restart the agent, then retry.

Symptomgit commit -S hangs in a terminal and always fails in CI.

Causegpg wants an interactive passphrase, which cannot exist without a TTY.

FixIn CI use gpg --batch --pinentry-mode loopback with the agent cache, and confirm it with gpgconf --kill gpg-agent before committing.

SymptomAn exported secret key gets committed to a repo or pasted into a chat app.

Causegpg --export-secret-keys -a KEYID emits a directly usable private key; leaking it forfeits the whole identity.

FixRevoke and regenerate: gpg --delete-secret-key KEYID plus a revocation of the public key. Keep private keys in a password manager or offline backup.

Troubleshooting

1Signature verification failed: compare fingerprints, then trust
gpg --fingerprint KEYID && gpg --verify document.txt.sig document.txt
The fingerprint must match what the other party published. Matching fingerprints plus a warning means trust is unset, not that the key is wrong.
2Find a key by email
gpg --search-keys "user@domain.com"
Then fetch precisely with gpg --recv-keys KEYID rather than passing the email directly.
3Confirm local key material is complete
gpg --list-keys && gpg --list-secret-keys
Public keys present but no secret keys means the private half is missing or deleted, and signing will fail.
4Reset the agent when it misbehaves
gpgconf --kill gpg-agent
Stale passphrase cache, password changes not taking effect and gpg hangs all start here.

Tips

Sign Git commits: git config --global commit.gpgsign true with a GPG key.
gpg --armor (-a) produces ASCII keys/signatures for easy text transfer.
Back up keys: gpg --export-secret-keys -a KEYID > private.asc, store safely.
gpg-agent caches the passphrase so you don't retype it.
gpgconf --kill gpg-agent restarts the agent to fix cache issues.
A key fingerprint verifies authenticity - always check it after importing.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Linux man-pages

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.