← Full reference

gpg

GnuPG — keys, encryption for a recipient and with a password, signatures, export and import, use in scripts

gpg (GnuPG) encrypts and signs files using the OpenPGP standard. There are two encryption modes: asymmetric — for the owner of a public key (-e -r), only they can decrypt it with their secret key; symmetric — with a password (-c). A signature (-s, -b) proves who created a file and that it hasn't been modified. Keys are stored in ~/.gnupg (or in the directory from GNUPGHOME), and secret keys are managed by the gpg-agent background process.

Syntax

gpg [options] command [file…]

The result is written next to the source file (file.gpg, file.asc, file.sig) or wherever -o points. Status messages go to stderr.

Keys

CommandWhat it does
--quick-gen-key 'Name <email>' [algo] [usage] [expiry]create a key with one command; default default never — defaults, no expiry
--gen-keycreate a key interactively (asks for name and email)
--full-generate-keyinteractively with all questions: algorithm, size, expiry
-k, --list-keys [who]public keys
-K, --list-secret-keys [who]secret keys
--fingerprint [who]key fingerprints (to verify over another channel)
--export [-a] whoexport a public key
--export-secret-keys -a whoexport a secret key (for a backup)
--import fileimport keys from a file
--delete-keys who / --delete-secret-keys whodelete a public / secret key
--delete-secret-and-public-key fingerprintdelete both
--edit-key whointeractive menu: trust, expire, passwd, adduid…
--lsign-key whosign someone else's key locally, i.e. mark it as trusted
--generate-revocation whorevocation certificate (one is already placed in openpgp-revocs.d/ when the key is created)

"Who" is an email, part of the name, the key ID or fingerprint.

Encryption and signatures

CommandWhat it does
-e, --encrypt -r recipientencrypt for a recipient; -r can be repeated
-c, --symmetricencrypt with a password (AES256)
-d, --decryptdecrypt (and verify the signature if one is inside) to stdout or to -o
-s, --signsign: file and signature together, in binary form
--clear-signa signature attached to text, the text itself stays readable
-b, --detach-signsignature in a separate .sig file (or .asc with -a)
--verify signature [file]verify a signature; for a detached signature also give the file
-se -r whosign and encrypt in one pass

Common options

OptionWhat it does
-a, --armortext form (-----BEGIN PGP …) instead of binary
-o filewhere to write the result; -o - — stdout
-u whowhich secret key to sign with
-r whorecipient
--batchnever ask anything — for scripts
--yesanswer "yes" (e.g. to overwriting a file)
-q / -vquieter / more verbose
--passphrase password / --passphrase-file file / --passphrase-fd 0password without a prompt (only together with --batch)
--pinentry-mode loopbacktake the secret key's password from --passphrase* rather than a pinentry window
--trust-model alwaysdon't ask about trust in the recipient's key
--homedir directorya different key directory (or the GNUPGHOME variable)
--keyid-format longshow long key IDs
--with-colonsmachine-readable list output

Reading the key list

pub   ed25519 2026-10-13 [SC] [expires: 2027-10-13]
      AC3AF46A56A58FA3A3DEA82BEA804362494F223C
uid           [ultimate] Alice <alice@example.com>
sub   cv25519 2026-10-13 [E]

pub/sec — the primary key (public/secret), sub/ssb — a subkey; the long string is the fingerprint. Usage letters: S — signing, C — certifying keys, E — encryption, A — authentication. In brackets next to uid is the trust level: ultimate — your own key, unknown — an imported one you don't trust yet.

Examples

# a separate key directory — doesn't touch your main ~/.gnupg
export GNUPGHOME=$(mktemp -d)

# a key without a password in one command (for tests and automation)
gpg --batch --passphrase '' --quick-gen-key 'Alice <alice@example.com>' default default never
gpg -k

# encrypt for a recipient and decrypt
echo 'top secret' > msg.txt
gpg -e -r alice@example.com msg.txt              # → msg.txt.gpg
gpg -d msg.txt.gpg                                # text to stdout
gpg -q -d -o plain.txt msg.txt.gpg                # to a file

# text form — handy to paste into an email or YAML
gpg -a -e -r alice@example.com -o msg.asc msg.txt

# with a password, no questions — in a script
gpg --batch --yes --passphrase 'pw' -c -o backup.tar.gpg backup.tar
gpg --batch --passphrase 'pw' -d -o backup.tar backup.tar.gpg

# password from a file rather than the command line
gpg --batch --passphrase-file /root/.backup-pass -d backup.tar.gpg > backup.tar

# a detached signature for a release and its verification
gpg -u alice@example.com -b -o release.tar.sig release.tar
gpg --verify release.tar.sig release.tar

# exchanging keys
gpg -a --export alice@example.com > alice.pub
gpg --import alice.pub
gpg --fingerprint alice@example.com

# in a script, when the secret key is password-protected
gpg --batch --pinentry-mode loopback --passphrase "$KEY_PASS" -d secret.gpg

# delete a key without questions (in batch mode — only by fingerprint)
gpg --batch --yes --delete-secret-and-public-key AC3AF46A56A58FA3A3DEA82BEA804362494F223C

Exit codes

0 — success (signature valid, decrypted); 1 — signature invalid (BAD signature); 2 — other errors: missing key, wrong password, refusal due to trust.

Pitfalls

  • The secret key's password isn't accepted in --batch without --pinentry-mode loopback. The error is Inappropriate ioctl for device. For symmetric -c and for key generation --batch --passphrase is enough.
  • gpg-agent caches the key's password. After one successful entry, subsequent decryptions go through without a password. To check that a password is really required, reset the agent: gpgconf --kill gpg-agent.
  • An imported key is "untrusted". gpg --batch -e -r … refuses to encrypt: There is no assurance this key belongs to the named user … Unusable public key. Verify the fingerprint and sign the key (--lsign-key), or in automation explicitly pass --trust-model always.
  • The output file already exists. Without --yes, gpg asks about overwriting; in --batch it fails with File exists, and without a terminal with cannot open '/dev/tty'. Add --batch --yes in scripts.
  • --verify of an embedded signature doesn't check an external file. gpg --verify file.asc file for a --clear-sign signature warns not a detached signature; file … was NOT verified. To verify a separate file, create the signature with -b.
  • --passphrase on the command line is visible in ps and stays in the history. Use --passphrase-file or --passphrase-fd.
  • Deletion in batch mode works only by fingerprint. By email you get can't do this in batch mode (unless you specify the key by fingerprint). And the secret key is deleted first, then the public one — or both at once with --delete-secret-and-public-key.
  • --quick-gen-key with the same uid a second time refuses: A key for "…" already exists. Add --yes if you really need a second key.
  • Key directory permissions. GNUPGHOME must be owned by you and have 700 permissions, otherwise every command prints WARNING: unsafe permissions on homedir. A directory from mktemp -d already fits.

See also

openssl · checksums · base64 · ssh · tar