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
| Command | What it does |
|---|---|
--quick-gen-key 'Name <email>' [algo] [usage] [expiry] | create a key with one command; default default never — defaults, no expiry |
--gen-key | create a key interactively (asks for name and email) |
--full-generate-key | interactively 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] who | export a public key |
--export-secret-keys -a who | export a secret key (for a backup) |
--import file | import keys from a file |
--delete-keys who / --delete-secret-keys who | delete a public / secret key |
--delete-secret-and-public-key fingerprint | delete both |
--edit-key who | interactive menu: trust, expire, passwd, adduid… |
--lsign-key who | sign someone else's key locally, i.e. mark it as trusted |
--generate-revocation who | revocation 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
| Command | What it does |
|---|---|
-e, --encrypt -r recipient | encrypt for a recipient; -r can be repeated |
-c, --symmetric | encrypt with a password (AES256) |
-d, --decrypt | decrypt (and verify the signature if one is inside) to stdout or to -o |
-s, --sign | sign: file and signature together, in binary form |
--clear-sign | a signature attached to text, the text itself stays readable |
-b, --detach-sign | signature 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 who | sign and encrypt in one pass |
Common options
| Option | What it does |
|---|---|
-a, --armor | text form (-----BEGIN PGP …) instead of binary |
-o file | where to write the result; -o - — stdout |
-u who | which secret key to sign with |
-r who | recipient |
--batch | never ask anything — for scripts |
--yes | answer "yes" (e.g. to overwriting a file) |
-q / -v | quieter / more verbose |
--passphrase password / --passphrase-file file / --passphrase-fd 0 | password without a prompt (only together with --batch) |
--pinentry-mode loopback | take the secret key's password from --passphrase* rather than a pinentry window |
--trust-model always | don't ask about trust in the recipient's key |
--homedir directory | a different key directory (or the GNUPGHOME variable) |
--keyid-format long | show long key IDs |
--with-colons | machine-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
--batchwithout--pinentry-mode loopback. The error isInappropriate ioctl for device. For symmetric-cand for key generation--batch --passphraseis enough. gpg-agentcaches 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,gpgasks about overwriting; in--batchit fails withFile exists, and without a terminal withcannot open '/dev/tty'. Add--batch --yesin scripts. --verifyof an embedded signature doesn't check an external file.gpg --verify file.asc filefor a--clear-signsignature warnsnot a detached signature; file … was NOT verified. To verify a separate file, create the signature with-b.--passphraseon the command line is visible inpsand stays in the history. Use--passphrase-fileor--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-keywith the sameuida second time refuses:A key for "…" already exists. Add--yesif you really need a second key.- Key directory permissions.
GNUPGHOMEmust be owned by you and have700permissions, otherwise every command printsWARNING: unsafe permissions on homedir. A directory frommktemp -dalready fits.