GPG(1)

GPG(1) — GNU Privacy Guard 1.4 💖✨

NAME 🎀

gpg — OpenPGP encryption and signing tool

SYNOPSIS 🌸

gpg [--homedir dir] [--options file] [options] command [args]

DESCRIPTION 💫

okay so bestie, gpg is the OpenPGP-only version of the GNU Privacy Guard (GnuPG). It's literally the tool that gives you digital encryption and signing services using the OpenPGP standard, and it comes with complete key management plus all the bells and whistles you'd expect from a decent OpenPGP implementation. periodt. 💅

This is the standalone version of gpg. For desktop use you should consider using gpg2 from the GnuPG-2 package ([On some platforms gpg2 is installed under the name gpg]). 🫶

RETURN VALUE 🩷

The program returns 0 if everything was fine, 1 if at least a signature was bad, and other error codes for fatal errors. no cap.

WARNINGS 😭

Use a good password for your user account and a good passphrase to protect your secret key. This passphrase is the weakest part of the whole system. Programs to do dictionary attacks on your secret keyring are very easy to write and so you should protect your ~/.gnupg/ directory very well. 🚨

Keep in mind that, if this program is used over a network (telnet), it is very easy to spy out your passphrase! 💀

If you are going to verify detached signatures, make sure that the program knows about it; either give both filenames on the command line or use - to specify STDIN. 👀

INTEROPERABILITY 🌈

GnuPG tries to be a very flexible implementation of the OpenPGP standard. In particular, GnuPG implements many of the optional parts of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2 compression algorithms. It is important to be aware that not all OpenPGP programs implement these optional algorithms and that by forcing their use via the --cipher-algo, --digest-algo, --cert-digest-algo, or --compress-algo options in GnuPG, it is possible to create a perfectly valid OpenPGP message, but one that cannot be read by the intended recipient. 😬

There are dozens of variations of OpenPGP programs available, and each supports a slightly different subset of these optional algorithms. For example, until recently, no (unhacked) version of PGP supported the BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be read by a PGP user. By default, GnuPG uses the standard OpenPGP preferences system that will always do the right thing and create messages that are usable by all recipients, regardless of which OpenPGP program they use. Only override this safe default if you really know what you are doing. ✨

If you absolutely must override the safe default, or if the preferences on a given key are invalid for some reason, you are far better off using the --pgp6, --pgp7, or --pgp8 options. These options are safe as they do not force any particular algorithms in violation of OpenPGP, but rather reduce the available algorithms to a "PGP-safe" list. 🧚

COMMANDS 👑

Commands are not distinguished from options except for the fact that only one command is allowed.

gpg may be run with no commands, in which case it will perform a reasonable action depending on the type of file it is given as input (an encrypted message is decrypted, a signature is verified, a file containing keys is listed). it's giving main character energy.

Please remember that option as well as command parsing stops as soon as a non-option is encountered, you can explicitly stop parsing by using the special option --. 💅

Commands not specific to the function ✨

• --version — Print the program version and licensing information. Note that you cannot abbreviate this command.
• --help, -h — Print a usage message summarizing the most useful command line options. Note that you cannot abbreviate this command.
• --warranty — Print warranty information.
• --dump-options — Print a list of all available options and commands. Note that you cannot abbreviate this command.

Commands to select the type of operation 🦋

• --sign, -s — Make a signature. This command may be combined with --encrypt (for a signed and encrypted message), --symmetric (for a signed and symmetrically encrypted message), or --encrypt and --symmetric together (for a signed message that may be decrypted via a secret key or a passphrase). The key to be used for signing is chosen by default or can be set with the --local-user and --default-key options. 🔥
• --clearsign — Make a clear text signature. The content in a clear text signature is readable without any special software. OpenPGP software is only needed to verify the signature. Clear text signatures may modify end-of-line whitespace for platform independence and are not intended to be reversible. The key to be used for signing is chosen by default or can be set with the --local-user and --default-key options. 📝
• --detach-sign, -b — Make a detached signature. 🎀
• --encrypt, -e — Encrypt data. This option may be combined with --sign (for a signed and encrypted message), --symmetric (for a message that may be decrypted via a secret key or a passphrase), or --sign and --symmetric together (for a signed message that may be decrypted via a secret key or a passphrase). 🔐
• --symmetric, -c — Encrypt with a symmetric cipher using a passphrase. The default symmetric cipher used is AES128, but may be chosen with the --cipher-algo option. This option may be combined with --sign (for a signed and symmetrically encrypted message), --encrypt (for a message that may be decrypted via a secret key or a passphrase), or --sign and --encrypt together (for a signed message that may be decrypted via a secret key or a passphrase). 🗝️
• --store — Store only (make a simple RFC1991 literal data packet). 📦
• --decrypt, -d — Decrypt the file given on the command line (or STDIN if no file is specified) and write it to STDOUT (or the file specified with --output). If the decrypted file is signed, the signature is also verified. This command differs from the default operation, as it never writes to the filename which is included in the file and it rejects files which don't begin with an encrypted message. 🔓
• --verify — Assume that the first argument is a signed file and verify it without generating any output. With no arguments, the signature packet is read from STDIN. If only a one argument is given, it is expected to be a complete signature.

With more than 1 argument, the first should be a detached signature and the remaining files make up the the signed data. To read the signed data from STDIN, use - as the second filename. For security reasons a detached signature cannot read the signed material from STDIN without denoting it in the above way.

Note: If the option --batch is not used, gpg may assume that a single argument is a file with a detached signature and it will try to find a matching data file by stripping certain suffixes. Using this historical feature to verify a detached signature is strongly discouraged; always specify the data file too.

Note: When verifying a cleartext signature, gpg verifies only what makes up the cleartext signed data and not any extra data outside of the cleartext signature or header lines following directly the dash marker line. The option --output may be used to write out the actual signed data; but there are other pitfalls with this format as well. It is suggested to avoid cleartext signatures in favor of detached signatures. 🫶

• --multifile — This modifies certain other commands to accept multiple files for processing on the command line or read from STDIN with each filename on a separate line. This allows for many files to be processed at once. --multifile may currently be used along with --verify, --encrypt, and --decrypt. Note that --multifile --verify may not be used with detached signatures. 🗂️
• --verify-files — Identical to --multifile --verify.
• --encrypt-files — Identical to --multifile --encrypt.
• --decrypt-files — Identical to --multifile --decrypt.
• --list-keys, -k, --list-public-keys — List all keys from the public keyrings, or just the keys given on the command line.

-k is slightly different from --list-keys in that it allows only for one argument and takes the second argument as the keyring to search. This is for command line compatibility with PGP 2 and has been removed in gpg2.

Avoid using the output of this command in scripts or other programs as it is likely to change as GnuPG changes. See --with-colons for a machine-parseable key listing command that is appropriate for use in scripts and other programs. 👑

• --list-secret-keys, -K — List all keys from the secret keyrings, or just the ones given on the command line. A # after the letters sec means that the secret key is not usable (for example, if it was created via --export-secret-subkeys). 🔐
• --list-sigs — Same as --list-keys, but the signatures are listed too.

For each signature listed, there are several flags in between the "sig" tag and keyid. These flags give additional information about each signature. From left to right, they are the numbers 1-3 for certificate check level (see --ask-cert-level), "L" for a local or non-exportable signature (see --lsign-key), "R" for a nonRevocable signature (see the --edit-key command "nrsign"), "P" for a signature that contains a policy URL (see --cert-policy-url), "N" for a signature that contains a notation (see --cert-notation), "X" for an eXpired signature (see --ask-cert-expire), and the numbers 1-9 or "T" for 10 and above to indicate trust signature levels (see the --edit-key command "tsign"). 🌟

• --check-sigs — Same as --list-sigs, but the signatures are verified. Note that for performance reasons the revocation status of a signing key is not shown.

The status of the verification is indicated by a flag directly following the "sig" tag (and thus before the flags described above for --list-sigs). A "!" indicates that the signature has been successfully verified, a "-" denotes a bad signature and a "%" is used if an error occurred while checking the signature (e.g. a non supported algorithm). 💯

• --fingerprint — bestie this is the glow-up of --list-keys. It lists all your keys (or just the ones you named) with their fingerprints, so you get the normal key dump plus a lil extra line showing the fingerprint ✨. You can also pair it with --list-sigs or --check-sigs and it plays nice. And if you pass this command twice?? iconic behaviour, it also lists the fingerprints of all secondary keys. periodt 💅
• --list-packets — just dumps the raw sequence of packets, one after another. It's giving debug mode, ngl — mainly useful for debugging 🔍.
• --card-edit — pops open a whole menu for working with a smartcard 🎀. Type the subcommand help inside it and it gives you an overview of all the available commands. For the full detailed breakdown, the Card HOWTO lives at https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO 🦋
• --card-status — shows you what's actually on the smart card. vibe check for your hardware 💳
• --change-pin — opens a menu so you can change the PIN on a smartcard 🔐. Same thing is also reachable as the subcommand passwd from inside --card-edit, iykyk.
• --delete-key name — yeets a key out of your public keyring 💀. In batch mode you either need --yes or you have to specify the key by fingerprint — that's a safeguard so nobody accidentally deletes a whole pile of keys, which, understandable honestly.
• --delete-secret-key name — same deal but for the secret keyring. In batch mode the key must be specified by fingerprint. no shortcuts bestie 🫶
• --delete-secret-and-public-key name — does what --delete-key does, but if a secret key exists it gets removed first. In batch mode the key must be specified by fingerprint.
• --export — exports all your keys from all keyrings (the default keyrings plus any registered via --keyring), or, if you give at least one name, just the ones matching that name ✨. Output goes to STDOUT, or into whatever file you gave with --output. Team it up with --armor if you're gonna mail those keys out 📬
• --send-keys key IDs — basically --export but it ships the keys off to a keyserver instead. You can use fingerprints instead of key IDs, and you must use --keyserver to say which keyserver. okay real talk: do NOT send your entire keyring to a keyserver — only send the keys that are new or that you changed. And if you give no key IDs at all, gpg just… does nothing. it's giving "I'm not gonna do it, girl" 😭
• --export-secret-keys, --export-secret-subkeys — same as --export but it exports the secret keys 😳. Output goes to STDOUT or to the file from --output. People often run this with --armor so the key is easy to print out as a paper backup — though the external tool paperkey actually does a better job at making backups on paper 📄. And heads up: exporting a secret key is a security risk if those exported keys get sent over an insecure channel 💀

The second form, --export-secret-subkeys, has a special property: it renders the secret part of the primary key useless. That's a GNU extension to OpenPGP, and other implementations can't be expected to successfully import a key like that. The intended use? Generate a full key with an extra signing subkey on a dedicated machine, then use this command to export the key without the primary key over to your main machine 🖥️

Also see the option --simple-sk-checksum if you want to import an exported secret key into ancient OpenPGP implementations (yes, ancient, we're talking museum vibes).

• --import, --fast-import — imports/merges keys, adding the given keys to your keyring 🎀. The fast version is currently just a synonym, so no flex there. A few other options control how this command behaves — most notable is --import-options merge-only, which does not insert new keys but only merges in new signatures, user-IDs and subkeys. obsessed with that ✨
• --recv-keys key IDs — imports the keys with those key IDs from a keyserver. You must use --keyserver to say which keyserver 🌈
• --refresh-keys — asks a keyserver for updates on keys that already live on your local keyring. Super useful for getting a key's latest signatures, user IDs, etc. Call it with no arguments and it refreshes the entire keyring 🫠. You must use --keyserver to name the keyserver for all keys that don't have preferred keyservers set (peep --keyserver-options honor-keyserver-url).
• --search-keys names — searches the keyserver for the names you give. Multiple names get joined together into one search string for the keyserver 🔎. You must use --keyserver to name the server. Keyservers that support different search methods let you use the syntax described in "How to specify a user ID" below — but note that different keyserver types support different search methods. Currently only LDAP supports them all, main character energy fr fr 👑
• --fetch-keys URIs — grabs keys that are located at the URIs you specify. Keep in mind different installations of GnuPG may support different protocols (HTTP, FTP, LDAP, etc.) so it's a lil ymmv 🌸
• --update-trustdb — trust database maintenance time 🧹. This command walks over every key and builds the Web of Trust. It's interactive because it may have to ask you for the "ownertrust" values of keys — you, yes you, have to estimate how far you trust the owner of the displayed key to correctly certify (sign) other keys 🫶. GnuPG only asks for an ownertrust value if it hasn't been assigned to a key yet. And through the --edit-key menu you can change an assigned value whenever you want ✨
• --check-trustdb — same trust database maintenance, but with zero user interaction 🙈. Every so often the trust database has to be updated so expired keys or signatures and the resulting Web of Trust changes get tracked. Normally GnuPG figures out when this is needed and does it automatically — unless --no-auto-check-trustdb is set. This command forces a trust database check any time you want. The processing is identical to --update-trustdb, except it skips keys with a not-yet-defined "ownertrust".

For cron jobs you can run this together with --batch, in which case the check only happens if one is actually needed. Wanna force a run even in batch mode? Add --yes 💅

• --export-ownertrust — sends the ownertrust values to STDOUT. Great for backups, because these values are the only ones that can't be re-created from a corrupted trustdb 😭. Example:

gpg --export-ownertrust > otrust.txt

• --import-ownertrust — updates the trustdb with the ownertrust values stored in files (or STDIN if you don't give any) — existing values get overwritten, no cap. If your trustdb is severely damaged and you have a recent backup of the ownertrust values (say, in the file otrust.txt), you can re-create the trustdb with these commands:

cd ~/.gnupg
rm trustdb.gpg
gpg --import-ownertrust < otrust.txt

• --rebuild-keydb-caches — back when you updated from version 1.0.6 to 1.0.7, you were supposed to run this to create signature caches in the keyring 📼. It might come in handy in other situations too, so keep it in your pocket.
• --print-md algo, --print-mds — prints the message digest of algorithm ALGO for all the files you gave (or for STDIN). With the second form — or with a deprecated * as algo — it prints digests for all available algorithms 🌈
• --gen-random 0|1|2 count — emits count random bytes at the quality level you pick: 0, 1, or 2 🎲. If count isn't given or is zero, it emits an endless stream of random bytes (okay??). If you use it with --armor, the output comes out base64 encoded. And like — PLEASE, don't use this command unless you genuinely know what you're doing; it may remove precious entropy from the system 💀😭
• --gen-prime mode bits — "Use the source, Luke :-)." That's the whole description bestie. The output format is still subject to change, so don't build your whole life on it 🦋
• --enarmor, --dearmor — packs or unpacks an arbitrary input into/from an OpenPGP ASCII armor 🎀. It's a GnuPG extension to OpenPGP and, in general, not very useful. lowkey a flop but she's here 💅

---

💖 How to manage your keys 💖

This section explains the main commands for key management ✨

• --gen-key — generates a brand new key pair using the current default parameters 🔑. This is the standard command for making a new key, no notes.

There's also a feature that lets you create keys in batch mode 🤖. Check the manual section "Unattended key generation" to find out how to use it.

• --gen-revoke name — generates a revocation certificate for the complete key 💔. If you only want to revoke a subkey or a signature, use the --edit command instead.
• --desig-revoke name — generates a designated revocation certificate for a key. This lets a user (with the permission of the keyholder, obviously, consent is key 🫶) revoke someone else's key.
• --edit-key — opens a menu that lets you do most of the key management related tasks 👑. It expects you to specify a key on the command line.
  • uid n — toggles selection of the user ID or photographic user ID with index n. Use * to select all and 0 to deselect all.
  • key n — toggles selection of the subkey with index n. Use * to select all and 0 to deselect all.
  • sign — makes a signature on the key of user name ✍️. If the key hasn't been signed yet by the default user (or by the users given with -u), the program shows you the key's information again, along with its fingerprint, and asks whether it should be signed. This question gets repeated for every user you specified with -u.
  • lsign — same as sign, but the signature is marked as non-exportable and will therefore never be used by others 🙈. This can be used to make keys valid only in the local environment — very "just for us" energy.
  • nrsign — same as sign, but the signature is marked as non-revocable and can therefore never be revoked 💀. Forever means forever, bestie.
  • tsign — makes a trust signature. This is a signature that combines the notions of certification (like a regular signature) and trust (like the trust command) 🤝. It's generally only useful in distinct communities or groups, so niche but valid ✨
• Note that l (for local / non-exportable), nr (for non-revocable), and t (for trust) can be freely mixed and prefixed to sign to build a signature of literally any type you want. mix-and-match queen behavior fr 💅
• delsig — Delete a signature. 💀 Ok but listen — once a signature has been sent out into the public (i.e. to a keyserver), you cannot retract it. It's out there, it's living its life, it's not coming back. In that case, bestie, you're way better off using revsig.
• revsig — Revoke a signature. For every signature that was generated by one of the secret keys, GnuPG asks you whether a revocation certificate should be generated. 🎀
• check — Check the signatures on all selected user IDs. vibe check, but for sigs ✨
• adduid — Create an additional user ID. more identity, more you 🫶
• addphoto — Create a photographic user ID. This prompts you for a JPEG file that gets embedded into the user ID. Note that a very large JPEG makes for a very large key (ngl, size matters here). Also note that some programs display your JPEG unchanged (GnuPG does this), and some programs scale it to fit inside a dialog box (PGP does that). 🙈
• showphoto — Display the selected photographic user ID. 📸
• deluid — Delete a user ID or photographic user ID. Note that once a user id has been sent to the public (i.e. to a keyserver), you cannot retract it — same rules as before, no takebacks. In that case you better use revuid. 😭
• revuid — Revoke a user ID or photographic user ID.
• primary — Flag the current user id as the primary one, removes the primary user id flag from all other user ids, and sets the timestamp of all affected self-signatures one second ahead. Note that setting a photo user ID as primary makes it primary over other photo user IDs, and setting a regular user ID as primary makes it primary over other regular user IDs. the way it keeps two separate leaderboards? iconic.
• keyserver — Set a preferred keyserver for the specified user ID(s). This lets other users know where you prefer they get your key from. See --keyserver-options honor-keyserver-url for more on how this works. Setting a value of "none" removes an existing preferred keyserver. 🌈
• notation — Set a name=value notation for the specified user ID(s). See --cert-notation for more on how this works. Setting a value of "none" removes all notations, setting a notation prefixed with a minus sign (-) removes that notation, and setting a notation name (without the =value) prefixed with a minus sign removes all notations with that name. precision removal, we love to see it 💅
• pref — List preferences from the selected user ID. This shows the actual preferences, without including any implied preferences. the raw, unfiltered truth.
• showpref — More verbose preferences listing for the selected user ID. This shows the preferences in effect by including the implied preferences of 3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they aren't already in the preference list. On top of that, the preferred keyserver and signature notations (if any) are shown too. ✨
• setpref string — Set the list of user ID preferences to string for all (or just the selected) user IDs. Calling setpref with no arguments sets the preference list to the default (either the built-in one or whatever was set via --default-preference-list), and calling setpref with "none" as the argument sets an empty preference list. Use gpg --version to get a list of available algorithms. Note that while you can change the preferences on an attribute user ID (aka a "photo ID"), GnuPG does not select keys via attribute user IDs, so these preferences won't be used by GnuPG.

When setting preferences, you should list the algorithms in the order you'd like to see them used by someone else when encrypting a message to your key. If you don't include 3DES, it gets automatically added at the end. Note that there are many factors that go into choosing an algorithm (for example, your key may not be the only recipient), and so the remote OpenPGP application being used to send to you may or may not follow your exact chosen order for a given message. It will, however, only choose an algorithm that is present on the preference list of every recipient key. See also the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below. 🔥

• addkey — Add a subkey to this key. baby key, welcome to the family 🍓
• addcardkey — Generate a subkey on a card and add it to this key.
• keytocard — Transfer the selected secret subkey (or the primary key if no subkey has been selected) to a smartcard. The secret key in the keyring gets replaced by a stub if the key could be stored successfully on the card and you use the save command later. Only certain key types may be transferred to the card. A sub menu lets you select which card to store the key on.

Ok bestie, real talk for a sec: it is not possible to get that key back from the card. If the card gets broken, your secret key is lost, unless you have a backup somewhere. Back it up. Back it up. Back it up. 🙈

• bkuptocard file — Restore the given file to a card. This command may be used to restore a backup key (as generated during card initialization) to a new card. In almost all cases this will be the encryption key. You should use this command only with the corresponding public key, and make sure that the file given as argument is indeed the backup you mean to restore. You should then select 2 to restore as encryption key. You'll first be asked to enter the passphrase of the backup key, and then for the Admin PIN of the card. 🔑
• delkey — Remove a subkey (secondart key). Note that once a subkey has been sent to the public (i.e. to a keyserver), you can't retract it — same energy as before. In that case you better use revkey.
• revkey — Revoke a subkey.
• expire — Change the key or subkey expiration time. If a subkey is selected, the expiration time of that subkey gets changed. With no selection, the key expiration of the primary key is changed. ⏳
• trust — Change the owner trust value for the key. This updates the trust-db immediately and no save is required. instant. no confirmation needed. 💅
• disable, enable — Disable or enable an entire key. A disabled key can not normally be used for encryption.
• addrevoker — Add a designated revoker to the key. This takes one optional argument: "sensitive". If a designated revoker is marked as sensitive, it will not be exported by default (see export-options).
• passwd — Change the passphrase of the secret key.
• toggle — Toggle between public and secret key listing. flip-flop, switch it up 🦋
• clean — Compact (by removing all signatures except the selfsig) any user ID that is no longer usable (e.g. revoked, or expired). Then, remove any signatures that aren't usable by the trust calculations. Specifically, this removes any signature that does not validate, any signature that is superseded by a later signature, revoked signatures, and signatures issued by keys that are not present on the keyring. ✨ decluttering the timeline, we love it.
• minimize — Make the key as small as possible. This removes all signatures from each user ID except for the most recent self-signature. ✂️
• cross-certify — Add cross-certification signatures to signing subkeys that may not currently have them. Cross-certification signatures protect against a subtle attack against signing subkeys. See --require-cross-certification. All new keys generated have this signature by default, so this option is only useful to bring older keys up to date. (glow-up for legacy keys, honestly 🫶)
• save — Save all changes to the key rings and quit.
• quit — Quit the program without updating the key rings. (not me exiting without saving 💀)

---

The listing shows you the key with its secondary keys and all user ids. The primary user id is indicated by a dot, and selected keys or user ids are indicated by an asterisk. The trust value is displayed with the primary key: the first is the assigned owner trust and the second is the calculated trust value. Letters are used for the values:

• - — No ownertrust assigned / not yet calculated.
• e — Trust calculation has failed; probably due to an expired key.
• q — Not enough information for calculation.
• n — Never trust this key.
• m — Marginally trusted.
• f — Fully trusted.
• u — Ultimately trusted. 👑

---

• --sign-key name — Signs a public key with your secret key. This is a shortcut version of the subcommand "sign" from --edit. ✨
• --lsign-key name — Signs a public key with your secret key but marks it as non-exportable. This is a shortcut version of the subcommand "lsign" from --edit-key.

---

✨ OPTIONS ✨

gpg comes with a whole bunch of options to control the exact behaviour and to change the default configuration. it's giving menu. it's giving build-your-own-adventure. 💅

Long options can be put in an options file (default "~/.gnupg/gpg.conf"). Short option names will not work — for example, "armor" is a valid option for the options file, while "a" is not. Do not write the 2 dashes — just the name of the option and any required arguments. Lines with a hash ('#') as the first non-white-space character are ignored. Commands may be put in this file too, but that's not generally useful as the command will execute automatically with every execution of gpg. 🫶

Please remember that option parsing stops as soon as a non-option is encountered. You can explicitly stop parsing by using the special option --.

---

🌸 How to change the configuration 🌸

okay so these next options? they're the config girlies — usually found chillin' in the option file. 💅

• --default-key name — Use name as the default key to sign with. If this option is not used, the default key is the first key found in the secret keyring. Note that -u or --local-user overrides this option.
• --default-recipient name — Use name as default recipient if option --recipient is not used and don't ask if this is a valid one. name must be non-empty.
• --default-recipient-self — Use the default key as default recipient if option --recipient is not used and don't ask if this is a valid one. The default key is the first one from the secret keyring or the one set with --default-key.
• --no-default-recipient — Reset --default-recipient and --default-recipient-self.
• -v, --verbose — Give more information during processing. If used twice, the input data is listed in detail.
• --no-verbose — Reset verbose level to 0.
• -q, --quiet — Try to be as quiet as possible.
• --batch, --no-batch — Use batch mode. Never ask, do not allow interactive commands. --no-batch disables this option. This option is commonly used for unattended operations.

WARNING: Unattended operation bears a higher risk of being exposed to security attacks. In particular any unattended use of GnuPG which involves the use of secret keys should take care not to provide an decryption oracle. There are several standard precautions against being used as an oracle. For example never return detailed error messages or any diagnostics printed by your software to the remote site. Consult with an expert in case of doubt. 😭

Note that even with a filename given on the command line, gpg might still need to read from STDIN (in particular if gpg figures that the input is a detached signature and no data file has been specified). Thus if you do not want to feed data via STDIN, you should connect STDIN to /dev/null.

• --no-tty — Make sure that the TTY (terminal) is never used for any output. This option is needed in some cases because GnuPG sometimes prints warnings to the TTY even if --batch is used.
• --yes — Assume "yes" on most questions.
• --no — Assume "no" on most questions.
• --list-options parameters — This is a space or comma delimited string that gives options used when listing keys and signatures (that is, --list-keys, --list-sigs, --list-public-keys, --list-secret-keys, and the --edit-key functions). Options can be prepended with a no- (after the two dashes) to give the opposite meaning. The options are:
  • show-photos — Causes --list-keys, --list-sigs, --list-public-keys, and --list-secret-keys to display any photo IDs attached to the key. Defaults to no. See also --photo-viewer. Does not work with --with-colons: see --attribute-fd for the appropriate way to get photo data for scripts and other frontends.
  • show-usage — Show usage information for keys and subkeys in the standard key listing. This is a list of letters indicating the allowed usage for a key (E=encryption, S=signing, C=certification, A=authentication). Defaults to no.
  • show-policy-urls — Show policy URLs in the --list-sigs or --check-sigs listings. Defaults to no.
  • show-notations, show-std-notations, show-user-notations — Show all, IETF standard, or user-defined signature notations in the --list-sigs or --check-sigs listings. Defaults to no.
  • show-keyserver-urls — Show any preferred keyserver URL in the --list-sigs or --check-sigs listings. Defaults to no.
  • show-uid-validity — Display the calculated validity of user IDs during key listings. Defaults to no.
  • show-unusable-uids — Show revoked and expired user IDs in key listings. Defaults to no.
  • show-unusable-subkeys — Show revoked and expired subkeys in key listings. Defaults to no.
  • show-keyring — Display the keyring name at the head of key listings to show which keyring a given key resides on. Defaults to no.
  • show-sig-expire — Show signature expiration dates (if any) during --list-sigs or --check-sigs listings. Defaults to no.
  • show-sig-subpackets — Include signature subpackets in the key listing. This option can take an optional argument list of the subpackets to list. If no argument is passed, list all subpackets. Defaults to no. This option is only meaningful when using --with-colons along with --list-sigs or --check-sigs.
• --verify-options parameters — This is a space or comma delimited string that gives options used when verifying signatures. Options can be prepended with a no- to give the opposite meaning. The options are:
  • show-photos — Display any photo IDs present on the key that issued the signature. Defaults to no. See also --photo-viewer.
  • show-policy-urls — Show policy URLs in the signature being verified. Defaults to no.
  • show-notations, show-std-notations, show-user-notations — Show all, IETF standard, or user-defined signature notations in the signature being verified. Defaults to IETF standard.
  • show-keyserver-urls — Show any preferred keyserver URL in the signature being verified. Defaults to no.
  • show-uid-validity — Display the calculated validity of the user IDs on the key that issued the signature. Defaults to no.
  • show-unusable-uids — Show revoked and expired user IDs during signature verification. Defaults to no.
  • show-primary-uid-only — Show only the primary user ID during signature verification. That is all the AKA lines as well as photo Ids are not shown with the signature verification status.
  • pka-lookups — Enable PKA lookups to verify sender addresses. Note that PKA is based on DNS, and so enabling this option may disclose information on when and what signatures are verified or to whom data is encrypted. This is similar to the "web bug" described for the auto-key-retrieve feature.
  • pka-trust-increase — Raise the trust in a signature to full if the signature passes PKA validation. This option is only meaningful if pka-lookups is set.
• --enable-large-rsa, --disable-large-rsa — With --gen-key and --batch, enable the creation of larger RSA secret keys than is generally recommended (up to 8192 bits). These large keys are more expensive to use, and their signatures and certifications are also larger.
• --enable-dsa2, --disable-dsa2 — Enable hash truncation for all DSA keys even for old DSA Keys up to 1024 bit. This is also the default with --openpgp. Note that older versions of GnuPG also required this flag to allow the generation of DSA larger than 1024 bit.
• --photo-viewer string — This is the command line that should be run to view a photo ID. "%i" will be expanded to a filename containing the photo. "%I" does the same, except the file will not be deleted once the viewer exits. Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" for the key fingerprint, "%t" for the extension of the image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), "%v" for the single-character calculated validity of the image being viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g. "full"), "%U" for a base32 encoded hash of the user ID, and "%%" for an actual percent sign. If neither %i or %I are present, then the photo will be supplied to the viewer on standard input.

The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN". Note that if your image viewer program is not secure, then executing it from GnuPG does not make it secure.

• --exec-path string — Sets a list of directories to search for photo viewers and keyserver helpers. If not provided, keyserver helpers use the compiled-in default directory, and photo viewers use the $PATH environment variable. Note, that on W32 system this value is ignored when searching for keyserver helpers.
• --keyring file — Add file to the current list of keyrings. If file begins with a tilde and a slash, these are replaced by the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME is not used).

Note that this adds a keyring to the current list. If the intent is to use the specified keyring alone, use --keyring along with --no-default-keyring.

• --secret-keyring file — Same as --keyring but for the secret keyrings.
• --primary-keyring file — Designate file as the primary public keyring. This means that newly imported keys (via --import or keyserver --recv-from) will go to this keyring.
• --trustdb-name file — Use file instead of the default trustdb. If file begins with a tilde and a slash, these are replaced by the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home directory (‘~/.gnupg’ if --homedir or $GNUPGHOME is not used).
• --homedir dir — Set the name of the home directory to dir. If this option is not used, the home directory defaults to ‘~/.gnupg’. It is only recognized when given on the command line. It also overrides any home directory stated through the environment variable ‘GNUPGHOME’ or (on Windows systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir.

okay so continuing the --homedir saga, because Windows is being extra 💅

On Windows systems it's possible to install GnuPG as a portable application. In that case only this command line option is considered, bestie — all other ways to set a home directory are just ignored, like, straight up.

To install GnuPG as a portable application under Windows, you create an empty file named gpgconf.ctl in the same directory as the tool gpgconf.exe. The root of the installation is then that directory; or, if gpgconf.exe has been installed directly below a directory named bin, then it's its parent directory. You also need to make sure these directories exist and are writable, no exceptions:

• ROOT/home — for the GnuPG home 🏠
• ROOT/var/cache/gnupg — for internal cache files 📦

---

• --pcsc-driver file — use file to access the smartcard reader. The current default is libpcsclite.so.1 for GLIBC based systems, /System/Library/Frameworks/PCSC.framework/PCSC for MAC OS X, winscard.dll for Windows and libpcsclite.so for other systems. 💳
• --disable-ccid — disable the integrated support for CCID compliant readers. This lets it fall back to one of the other drivers even if the internal CCID driver could handle the reader. Note (fr fr, important): CCID support is only available if libusb was available at build time. build-time tea ☕
• --reader-port number_or_string — this option may be used to specify the port of the card terminal. A value of 0 refers to the first serial device; add 32768 to access USB devices. The default is 32768 (first USB device). PC/SC or CCID readers might need a string here; run the program in verbose mode to get a list of available readers. The default is then the first reader found. 🔌
• --display-charset name — set the name of the native character set. This is used to convert some informational strings like user IDs to the proper UTF-8 encoding. careful though: this has nothing to do with the character set of data to be encrypted or signed; GnuPG does not recode user-supplied data. If this option is not used, the default character set is determined from the current locale. A verbosity level of 3 shows the chosen set. Valid values for name are:
  • iso-8859-1 — this is the Latin 1 set.
  • iso-8859-2 — the Latin 2 set.
  • iso-8859-15 — this is currently an alias for the Latin 1 set.
  • koi8-r — the usual Russian set (rfc1489).
  • utf-8 — bypass all translations and assume that the OS uses native UTF-8 encoding. ✨
• --utf8-strings, --no-utf8-strings — assume that command line arguments are given as UTF8 strings. The default (--no-utf8-strings) is to assume that arguments are encoded in the character set as specified by --display-charset. These options affect all following arguments. Both options may be used multiple times. 🔁
• --options file — read options from file and do not try to read them from the default options file in the homedir (see --homedir). This option is ignored if used in an options file. 🙈
• --no-options — shortcut for --options /dev/null. This option is detected before an attempt to open an option file. Using this option will also prevent the creation of a ~/.gnupg homedir. 🚫
• -z n, --compress-level n, --bzip2-compress-level n — set compression level to n for the ZIP and ZLIB compression algorithms. The default is to use the default compression level of zlib (normally 6). --bzip2-compress-level sets the compression level for the BZIP2 compression algorithm (defaulting to 6 as well). This is a different option from --compress-level since BZIP2 uses a significant amount of memory for each additional compression level. -z sets both. A value of 0 for n disables compression. 🗜️
• --bzip2-decompress-lowmem — use a different decompression method for BZIP2 compressed files. This alternate method uses a bit more than half the memory, but also runs at half the speed. This is useful under extreme low memory circumstances when the file was originally compressed at a high --bzip2-compress-level. 🐌
• --mangle-dos-filenames, --no-mangle-dos-filenames — older version of Windows cannot handle filenames with more than one dot. --mangle-dos-filenames causes GnuPG to replace (rather than add to) the extension of an output filename to avoid this problem. This option is off by default and has no effect on non-Windows platforms. 🪟
• --ask-cert-level, --no-ask-cert-level — when making a key signature, prompt for a certification level. If this option is not specified, the certification level used is set via --default-cert-level. See --default-cert-level for information on the specific levels and how they are used. --no-ask-cert-level disables this option. This option defaults to no. ❓
• --default-cert-level n — the default to use for the check level when signing a key.
  • 0 means you make no particular claim as to how carefully you verified the key.
  • 1 means you believe the key is owned by the person who claims to own it but you could not, or did not verify the key at all. This is useful for a "persona" verification, where you sign the key of a pseudonymous user.
  • 2 means you did casual verification of the key. For example, this could mean that you verified the key fingerprint and checked the user ID on the key against a photo ID.
  • 3 means you did extensive verification of the key. For example, this could mean that you verified the key fingerprint with the owner of the key in person, and that you checked, by means of a hard to forge document with a photo ID (such as a passport) that the name of the key owner matches the name in the user ID on the key, and finally that you verified (by exchange of email) that the email address on the key belongs to the key owner.

Note that the examples given above for levels 2 and 3 are just that: examples. In the end, it is up to you to decide just what "casual" and "extensive" mean to you. 💅

This option defaults to 0 (no particular claim).

• --min-cert-level — when building the trust database, treat any signatures with a certification level below this as invalid. Defaults to 2, which disregards level 1 signatures. Note that level 0 "no particular claim" signatures are always accepted. ✅
• --trusted-key long key ID — assume that the specified key (which must be given as a full 8 byte key ID) is as trustworthy as one of your own secret keys. This option is useful if you don't want to keep your secret keys (or one of them) online but still want to be able to check the validity of a given recipient's or signator's key. 🔑
• --trust-model pgp|classic|direct|always|auto — set what trust model GnuPG should follow. The models are:
  • pgp — this is the Web of Trust combined with trust signatures as used in PGP 5.x and later. This is the default trust model when creating a new trust database.
  • classic — this is the standard Web of Trust as introduced by PGP 2.
  • direct — key validity is set directly by the user and not calculated via the Web of Trust.
  • always — skip key validation and assume that used keys are always fully valid. You generally won't use this unless you are using some external validation scheme. This option also suppresses the "[uncertain]" tag printed with signature checks when there is no evidence that the user ID is bound to the key. Note that this trust model still does not allow the use of expired, revoked, or disabled keys. 🚫
  • auto — select the trust model depending on whatever the internal trust database says. This is the default model if such a database already exists. 🤖
• --auto-key-locate parameters, --no-auto-key-locate — GnuPG can automatically locate and retrieve keys as needed using this option. This happens when encrypting to an email address (in the "user@example.com" form), and there are no user@example.com keys on the local keyring. This option takes any number of the following mechanisms, in the order they are to be tried:
  • cert — locate a key using DNS CERT, as specified in rfc4398.
  • pka — locate a key using DNS PKA.
  • ldap — using DNS Service Discovery, check the domain in question for any LDAP keyservers to use. If this fails, attempt to locate the key using the PGP Universal method of checking 'ldap://keys.(thedomain)'.
  • keyserver — locate a key using whatever keyserver is defined using the --keyserver option.
  • keyserver-URL — in addition, a keyserver URL as used in the --keyserver option may be used here to query that particular keyserver.
  • local — locate the key using the local keyrings. This mechanism allows the user to select the order a local key lookup is done. Thus using '--auto-key-locate local' is identical to --no-auto-key-locate.
  • nodefault — this flag disables the standard local key lookup, done before any of the mechanisms defined by the --auto-key-locate are tried. The position of this mechanism in the list does not matter. It is not required if local is also used.
  • clear — clear all defined mechanisms. This is useful to override mechanisms given in a config file. 🧹
• --keyid-format short|0xshort|long|0xlong — select how to display key IDs. "short" is the traditional 8-character key ID. "long" is the more accurate (but less convenient) 16-character key ID. Add an "0x" to either to include an "0x" at the beginning of the key ID, as in 0x99242560. Note that this option is ignored if the option --with-colons is used. 🏷️
• --keyserver name — bestie this one sets ur keyserver, like the whole server that --recv-keys, --send-keys, and --search-keys talk to when they wanna grab keys, yeet keys out, or search for keys. 💌 The format of name is a URI:

scheme:[//]keyservername[:port]

The scheme is the type of keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP keyservers, or "mailto" for the Graff email keyserver. Heads up tho — ur particular GnuPG install might have other keyserver types available too, no cap. Keyserver schemes are case-insensitive (so HKP and hkp are giving the same thing 💅). After the keyserver name, u can drop optional keyserver config options — these are literally the same as the global --keyserver-options from down below, but they apply only to this one particular keyserver.

Also most keyservers sync with each other, so generally there's no need to send keys to more than one server, periodt. And the keyserver hkp://keys.gnupg.net uses round robin DNS to give u a different keyserver every single time u use it, which is lowkey iconic. ✨

• --keyserver-options name=value1 — this is a space or comma delimited string that gives options for the keyserver. Options can be prefixed with a no- to give the opposite meaning (the classic glow-down toggle ✨). Valid import-options or export-options may be used here as well, to apply to importing (--recv-key) or exporting (--send-key) a key from a keyserver. Not all options are available for all keyserver types, but here are some common ones, bestie:
  • include-revoked — when searching for a key with --search-keys, include keys that are marked on the keyserver as revoked. 🚫 Note that not all keyservers differentiate between revoked and unrevoked keys, and for those keyservers this option is literally meaningless. Also note that most keyservers do not have cryptographic verification of key revocations, so turning this option off may result in skipping keys that are incorrectly marked as revoked. 🙈
  • include-disabled — when searching for a key with --search-keys, include keys marked on the keyserver as disabled. Note that this option is not used with HKP keyservers.
  • auto-key-retrieve — this enables automatic retrieving of keys from a keyserver when verifying signatures made by keys that aren't on the local keyring. 🔥

Okay so real talk: this option makes a "web bug" like behavior possible. 👀 Keyserver operators can see which keys u request, so by sending u a message signed by a brand new key (which obviously u won't have on ur local keyring), the operator can tell both ur IP address and the time when u verified the signature. Not me being perceived without consent 😭

• honor-keyserver-url — when using --refresh-keys, if the key in question has a preferred keyserver URL, then use that preferred keyserver to refresh the key from. Also, if auto-key-retrieve is set and the signature being verified has a preferred keyserver URL, then use that preferred keyserver to fetch the key from. Defaults to yes.
• honor-pka-record — if auto-key-retrieve is set and the signature being verified has a PKA record, then use the PKA information to fetch the key. Defaults to yes.
• include-subkeys — when receiving a key, include subkeys as potential targets. Note that this option is not used with HKP keyservers, since they don't support retrieving keys by subkey id. 💔
• use-temp-files — on most Unix-like platforms, GnuPG communicates with the keyserver helper program via pipes, which is the most efficient method. This option forces GnuPG to use temporary files to communicate instead. On some platforms (like Win32 and RISC OS) this option is always enabled.
• keep-temp-files — if u use use-temp-files, do not delete the temp files after using them. This one is useful to learn the keyserver communication protocol by reading the temporary files. 🧚
• verbose — tell the keyserver helper program to be more verbose. Can be repeated multiple times to increase the verbosity level, she just keeps talking fr fr. 🔊
• timeout — tell the keyserver helper program how long (in seconds) to try and perform a keyserver action before giving up. Note that performing multiple actions at the same time uses this timeout value per action. For example, when retrieving multiple keys via --recv-keys, the timeout applies separately to each key retrieval, and not to the --recv-keys command as a whole. Defaults to 30 seconds.
• http-proxy=value — set the proxy to use for HTTP and HKP keyservers. This overrides the "http_proxy" environment variable, if any.
• max-cert-size — when retrieving a key via DNS CERT, only accept keys up to this size. Defaults to 16384 bytes.
• debug — turn on debug output in the keyserver helper program. Note that the details of debug output depend on which keyserver helper program is being used, and in turn, on any libraries that the keyserver helper program uses internally (libcurl, openldap, etc).
• check-cert — enable certificate checking if the keyserver presents one (for hkps or ldaps). Defaults to on.
• ca-cert-file — provide a certificate store to override the system default. Only necessary if check-cert is enabled, and the keyserver is using a certificate that is not present in a system default certificate list. 📜

Note that depending on the SSL library that the keyserver helper is built with, this may actually be a directory or a file. (ik ik, it's giving ambiguity 💀)

• --completes-needed n — number of completely trusted users to introduce a new key signer (defaults to 1).
• --marginals-needed n — number of marginally trusted users to introduce a new key signer (defaults to 3)
• --max-cert-depth n — maximum depth of a certification chain (default is 5).
• --simple-sk-checksum — okay so secret keys are integrity protected by using a SHA-1 checksum. This method is part of the upcoming enhanced OpenPGP specification, but GnuPG already uses it as a countermeasure against certain attacks. 🛡️ Old applications don't understand this new format, so this option may be used to switch back to the old behaviour.

⚠️ Using this option bears a security risk. Also note that using this option only takes effect when the secret key is encrypted — the simplest way to make this happen is to change the passphrase on the key (even changing it to the same value is acceptable). 💅

• --no-sig-cache — do not cache the verification status of key signatures. Caching gives a much better performance in key listings. However, if u suspect that ur public keyring is not save against write modifications, u can use this option to disable the caching. It probably does not make sense to disable it, because all kinds of damage can be done if someone else has write access to ur public keyring. 😭
• --no-sig-create-check — this option is obsolete. It has no function. That's it, that's the whole vibe check. 💀
• --auto-check-trustdb, --no-auto-check-trustdb — if GnuPG feels that its info about the Web of Trust has to be updated, it automatically runs the --check-trustdb command internally. This may be a time consuming process. 🐌 --no-auto-check-trustdb disables this option.
• --use-agent, --no-use-agent — try to use the GnuPG-Agent. With this option, GnuPG first tries to connect to the agent before it asks for a passphrase. --no-use-agent disables this option. Note that the tool gpg-preset-passphrase, which comes with GnuPG-2, cannot be used to preset a passphrase for this version of GnuPG. 🙅
• --gpg-agent-info — override the value of the environment variable GPG_AGENT_INFO. This is only used when --use-agent has been given. Given that this option is not anymore used by gpg2, it should be avoided if possible. 👋
• --lock-once — lock the databases the first time a lock is requested and do not release the lock until the process terminates. 🔒
• --lock-multiple — release the locks every time a lock is no longer needed. Use this to override a previous --lock-once from a config file.
• --lock-never — disable locking entirely. This option should be used only in very special environments, where it can be assured that only one process is accessing those files. A bootable floppy with a stand-alone encryption system will probably use this. Improper usage of this option may lead to data and key corruption. 💀
• --exit-on-status-write-error — this option will cause write errors on the status FD to immediately terminate the process. That should in fact be the default, but it never worked this way, and thus we need an option to enable this, so that the change won't break applications which close their end of a status fd connected pipe too early. 🙈 Using this option along with --enable-progress-filter may be used to cleanly cancel long running gpg operations.
• --limit-card-insert-tries n — with n greater than 0, the number of prompts asking to insert a smartcard gets limited to N-1. So with a value of 1, gpg won't at all ask to insert a card if none has been inserted at startup. This option is useful in the configuration file in case an application does not know about the smartcard support and waits ad infinitum for an inserted card. 🃏 (main character energy: the card that never arrives)
• --no-random-seed-file — GnuPG uses a file to store its internal random pool over invocations. This makes random generation faster; however sometimes write operations are not desired. This option can be used to achieve that, at the cost of slower random generation. 🎲
• --no-greeting — no copyright banner at the top, bestie. poof, gone. 💨
• --no-secmem-warning — shuts up the "using insecure memory" warning. it's still insecure, you just don't have to hear about it 😭
• --no-permission-warning — silences the warning about unsafe file perms and unsafe home directory (--homedir) perms. okay but real talk: the permission checks GnuPG does are not meant to be authoritative, they just flag common permission oopsies. do not assume that "no warning" = "my system is secure". it is not that. 🙈

⚠️ and listen: the warning for unsafe --homedir permissions can not be suppressed in the gpg.conf file, because then an attacker could just drop a sketchy gpg.conf in place and use it to suppress warnings about itself. iconic villain behavior, we're not doing that. the --homedir permissions warning may only be suppressed on the command line. periodt.

• --no-mdc-warning — kills the warning about missing MDC integrity protection. (missing MDC is lowkey a big deal, but okay bestie, you do you 💅)
• --require-secmem, --no-require-secmem — this one flat out refuses to run if GnuPG can't get secure memory. default is no, meaning: it runs anyway, it just gives you a warning. 🫶
• --require-cross-certification, --no-require-cross-certification — when verifying a signature made from a subkey, make sure the cross certification "back signature" on the subkey is there and valid. this protects against a subtle attack on subkeys that can sign 👀. defaults to --require-cross-certification for gpg.
• --expert, --no-expert — unlocks the ability to do certain nonsensical / "silly" things, like signing an expired or revoked key, or potentially incompatible stuff like generating unusual key types. it also disables certain warning messages about potentially incompatible actions. and like the name says: this is for experts only. if you don't fully understand the implications of what it lets you do, leave it OFF. --no-expert disables it. fr fr, this is the "trust me bro" of flags. 🙈

---

🔑 Key related options 🔑

• --recipient name, -r — encrypt for user id name. if this one or --hidden-recipient isn't given, GnuPG will just ask you for the user-id, unless --default-recipient is set. 💖
• --hidden-recipient name, -R — encrypt for user ID name, but hide the key ID of that user's key. this helps hide who the receiver is and is a limited countermeasure against traffic analysis 🕵️. if this or --recipient isn't specified, GnuPG asks for the user ID unless --default-recipient is given.
• --encrypt-to name — same as --recipient, but it's made for the options file, and you can use your own user-id as an "encrypt-to-self" ✨. these keys are only used when there are other recipients, either given by --recipient or by the user id it asked you for. no trust checking is performed for these user ids, and even disabled keys can be used. wild, but okay!
• --hidden-encrypt-to name — same as --hidden-recipient but meant for the options file, and you can use your own user-id as a hidden "encrypt-to-self" 🫣. again: only used when there are other recipients given by --recipient or by the asked user id. no trust checking performed, and even disabled keys can be used.
• --no-encrypt-to — disables the use of all --encrypt-to and --hidden-encrypt-to keys. bye bye 👋
• --group name=value1 — sets up a named group, which is like aliases in email programs 💌. any time the group name shows up as a recipient (-r or --recipient), it gets expanded to the values you gave. multiple groups with the same name get automatically merged into one single group.

the values are key IDs or fingerprints, but honestly any key description is accepted. heads up: a value with spaces in it will be treated as two different values. also note there is only one level of expansion — you cannot make a group that points to another group. no group-ception 🚫. and when you use it from the command line, you may need to quote the argument so the shell doesn't split it into multiple args.

• --ungroup name — removes a given entry from the --group list. 🧹
• --no-groups — removes all entries from the --group list.
• --local-user name, -u — use name as the key to sign with. note that this option overrides --default-key. 👑
• --try-all-secrets — don't look at the key ID stored in the message, just try all the secret keys in turn to find the right decryption key 🔓. this forces the behavior used by anonymous recipients (the ones created with --throw-keyids or --hidden-recipient), and it might come in handy when an encrypted message contains a bogus key ID. cute little rescue tool.

---

📥 Input and Output 📤

• --armor, -a — makes ASCII armored output ✨. the default is to create the binary OpenPGP format.
• --no-armor — assumes the input data is not in ASCII armored format.
• --output file, -o file — write output to file. 📝
• --max-output n — sets a limit on the number of bytes that will be generated while processing a file. since OpenPGP supports various levels of compression, the plaintext of a given message can be significantly larger than the original OpenPGP message 😳. GnuPG works fine with those, but often you want to cap how big the output can get before the OS limits force processing to stop. defaults to 0, which means "no limit". (famous last words tbh)
• --import-options parameters — a space or comma delimited string of options for importing keys. options can be prepended with a no- to mean the opposite. the options are:
  • import-local-sigs — allow importing key signatures marked as "local". not generally useful unless a shared keyring scheme is being used. defaults to no.
  • keep-ownertrust — normally, any still-existing ownertrust values of a key are cleared when that key is imported. this is generally desirable so a formerly deleted key doesn't automatically regain ownertrust values just because of an import. on the other hand, sometimes you need to re-import a trusted set of keys but keep the ownertrust values already assigned — this option is how you do that. 🫶
  • repair-pks-subkey-bug — during import, attempt to repair damage caused by the PKS keyserver bug (pre version 0.9.6) that mangles keys with multiple subkeys. note this cannot completely repair the damaged key, because some crucial data was removed by the keyserver — but it at least gives you back one subkey. defaults to no for regular --import and to yes for keyserver --recv-keys.
  • merge-only — during import, allow key updates to existing keys, but don't allow any new keys to be imported. defaults to no.
  • import-clean — after import, compact (remove all signatures except the self-signature) any user IDs from the new key that aren't usable. then remove any signatures from the new key that aren't usable, including signatures issued by keys that aren't on the keyring. same as running the --edit-key command "clean" after import. defaults to no.
  • import-minimal — import the smallest key possible 🐜. removes all signatures except the most recent self-signature on each user ID. same as running the --edit-key command "minimize" after import. defaults to no.
• --export-options parameters — a space or comma delimited string of options for exporting keys. options can be prepended with no- for the opposite meaning. the options are:
  • export-local-sigs — allow exporting key signatures marked as "local". not generally useful unless a shared keyring scheme is being used. defaults to no.
  • export-attributes — include attribute user IDs (photo IDs) while exporting 🖼️. useful if the keys are going to be used by an OpenPGP program that doesn't accept attribute user IDs. defaults to yes.
  • export-sensitive-revkeys — include designated revoker information that was marked as "sensitive". defaults to no.
  • export-reset-subkey-passwd — when using the --export-secret-subkeys command, this resets the passphrases for all exported subkeys to empty. useful when the exported subkey is going to live on an unattended machine where a passphrase doesn't necessarily make sense. defaults to no.
  • export-clean — compact (remove all signatures from) user IDs on the key being exported if those user IDs aren't usable. also don't export any signatures that aren't usable, including signatures issued by keys not present on the keyring. same as running the --edit-key command "clean" before export, except the local copy of the key is not modified. defaults to no.
  • export-minimal — export the smallest key possible. removes all signatures except the most recent self-signature on each user ID. same as running the --edit-key command "minimize" before export, except the local copy of the key is not modified. defaults to no.
• --with-colons — print key listings delimited by colons 🫶. note that the output will be encoded in UTF-8 regardless of any --display-charset setting. this format is great when GnuPG is called from scripts and other programs, because it's easily machine parsed. the details of this format are documented in the file doc/DETAILS, which is included in the GnuPG source distribution.
• --fixed-list-mode — bestie, this stops GPG from smooshing the primary user ID and the primary key together when you're in --with-colon listing mode, and it prints all timestamps as seconds since 1970-01-01. Raw epoch energy, we love to see it. 🕰️
• --with-fingerprint — literally the same as the command --fingerprint, except it only changes the format of the output, which means you can use it alongside another command. It's giving sidekick, not main character. ✨

💅 OpenPGP protocol specific options 💅

• -t, --textmode / --no-textmode — treats input files as text and stores them in the OpenPGP canonical text form with standard "CRLF" line endings. This also sets the necessary flags to let the recipient know the encrypted or signed data is text and might need its line endings converted back to whatever the local system uses. So useful when you're talking between two platforms that have different line ending conventions (UNIX-like to Mac, Mac to Windows, etc). And --no-textmode disables this whole thing — and yes, that's the default, no cap. 🌈

Also, if -t (but not --textmode) is used together with armoring and signing, this enables clearsigned messages. This kludge is needed for command-line compatibility with command-line versions of PGP; normally you'd just use --sign or --clearsign to pick the type of signature. She's a little hacked-together but she works 💅

• --force-v3-sigs / --no-force-v3-sigs — okay so OpenPGP says an implementation should generate v4 signatures, but PGP versions 5 through 7 only recognize v4 signatures on key material. So this option forces v3 signatures — but only for signatures on data. Heads up though: this implies --no-ask-sig-expire, and it unsets --sig-policy-url, --sig-notation, and --sig-keyserver-url, because those features literally cannot be used with v3 signatures. --no-force-v3-sigs disables it. Defaults to no. 🫶
• --force-v4-certs / --no-force-v4-certs — always use v4 key signatures, even on v3 keys. This also changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1. --no-force-v4-certs disables it. glow up tbh ⭐
• --force-mdc — forces the use of encryption with a modification detection code. This is always used with the newer ciphers (the ones with a blocksize greater than 64 bits), or if all of the recipient keys indicate MDC support in their feature flags. So it's kinda already there, but now you're forcing it fr fr. 🔥
• --disable-mdc — disables the use of the modification detection code.

bestie. listen. by using this option, the encrypted message becomes vulnerable to a message modification attack. That is not a vibe. Do not do this unless you genuinely know what you're doing 😭

• --personal-cipher-preferences string — sets your personal cipher preferences list to string. Run gpg --version to see the available algorithms, and use none if you want no preference at all. This lets you safely override the algorithm chosen by the recipient key preferences, because GPG will only ever pick an algorithm that's usable by all recipients. And the most highly ranked cipher in this list also gets used for the --symmetric encryption command. she's specific 💖
• --personal-digest-preferences string — sets your personal digest preferences list to string. gpg --version for the available algorithms, none for no preference at all. Same deal: safely overrides whatever the recipient key preferences chose, since GPG only selects an algorithm usable by all recipients. The most highly ranked digest algorithm in this list is also used when you're signing without encryption (e.g. --clearsign or --sign). ✨
• --personal-compress-preferences string — sets your personal compression preferences list to string. Again: gpg --version lists the available algorithms, none sets no preference. Again again: safely overrides the recipient key preference choice, and GPG only picks something usable by all recipients. The most highly ranked compression algorithm here also gets used when there are no recipient keys to consider (e.g. --symmetric). 🎀
• --s2k-cipher-algo name — use name as the cipher algorithm to protect secret keys. The default cipher is AES128. This cipher also gets used for conventional encryption if --personal-cipher-preferences and --cipher-algo are not given. 👑
• --s2k-digest-algo name — use name as the digest algorithm used to mangle the passphrases. The default algorithm is SHA-1. 🍓
• --s2k-mode n — selects how passphrases get mangled, and there are three moods:
  • n is 0 → a plain passphrase is used, which is not recommended 🙈
  • n is 1 → adds a salt to the passphrase
  • n is 3 → iterates the whole process a number of times (see --s2k-count), and this is the default

And unless --rfc1991 is used, this mode is also used for conventional encryption. multitasking icon 💅

• --s2k-count n — specify how many times the passphrase mangling gets repeated. n can range between 1024 and 65011712 inclusive. The default is inquired from gpg-agent. And ngl, not all values in the 1024-65011712 range are legal — if you pick an illegal value, GnuPG will round up to the nearest legal value. This option is only meaningful if --s2k-mode is 3. 🤓

🌸 Compliance options 🌸

These control what GnuPG is compliant to. Only one of these options may be active at a time. And just so you know, the default setting here is nearly always the correct one — so before you use any of these, go read the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below. iykyk 💜

• --gnupg — use standard GnuPG behavior. This is essentially OpenPGP behavior (see --openpgp), just with some extra workarounds for common compatibility problems in different versions of PGP. It's the default option so you generally don't need it, but it's handy for overriding a different compliance option that's chilling in your gpg.conf file. 🏠
• --openpgp — resets all packet, cipher and digest options to strict OpenPGP behavior. Use this to reset all previous options like --s2k-*, --cipher-algo, --digest-algo and --compress-algo back to OpenPGP compliant values. All PGP workarounds are disabled. clean slate bestie ✨
• --rfc4880 — resets all packet, cipher and digest options to strict RFC-4880 behavior. And note that this is currently the same thing as --openpgp. twins fr 👯
• --rfc2440 — resets all packet, cipher and digest options to strict RFC-2440 behavior.
• --rfc1991 — tries to be more RFC-1991 (PGP 2.x) compliant. This option is deprecated and will be removed in GnuPG 2.1. 🪦
• --pgp2 — sets up all options to be as PGP 2.x compliant as possible, and warns you if an action is taken (e.g. encrypting to a non-RSA key) that would create a message PGP 2.x cannot handle. Note that PGP 2.x here means MIT PGP 2.6.2. There are other versions of PGP 2.x floating around, but the MIT release is a good common baseline.

This option implies --rfc1991 --disable-mdc --no-force-v4-certs --escape-from-lines --force-v3-sigs --allow-weak-digest-algos --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP. It also disables --textmode when encrypting.

This option is deprecated and will be removed in GnuPG 2.1. The reason for dropping PGP-2 support is that the PGP 2 format is not considered safe anymore (for example, due to the use of the broken MD5 algorithm). Note though that decryption of PGP-2 created messages will continue to work. 🤝

• --pgp6 — sets up all options to be as PGP 6 compliant as possible. This restricts you to the ciphers IDEA (if the IDEA plugin is installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the compression algorithms none and ZIP. It also disables --throw-keyids, and it stops you making signatures with signing subkeys, because PGP 6 doesn't understand signatures made by signing subkeys. 💀

This option implies --disable-mdc --escape-from-lines --force-v3-sigs.

• --pgp7 — sets up all options to be as PGP 7 compliant as possible. This is identical to --pgp6 except that MDCs are not disabled, and the list of allowable ciphers is expanded to add AES128, AES192, AES256, and TWOFISH. upgrade era 💅
• --pgp8 — sets up all options to be as PGP 8 compliant as possible. PGP 8 is a lot closer to the OpenPGP standard than previous versions of PGP, so all this does is disable --throw-keyids and set --escape-from-lines. All algorithms are allowed except for the SHA224, SHA384, and SHA512 digests. so chill, so simple 🦋

😳 Doing things one usually doesn't want to do. 😳

• -n, --dry-run — don't make any changes. And fair warning: this is not completely implemented. 🙂‍↕️
• --list-only — changes the behaviour of some commands. This is like --dry-run but different in some cases. The semantic of this command may be extended in the future. Currently it only skips the actual decryption pass, which therefore enables a fast listing of the encryption keys. speedrun strat 🏃‍♀️
• -i, --interactive — prompt before overwriting any files. consent king 👑
• --debug-level level — selects the debug level for investigating problems. level can be a numeric value or a keyword:
  • none — no debugging at all. A value of less than 1 may be used instead of the keyword.
  • basic — some basic debug messages. A value between 1 and 2 may be used instead of the keyword.
  • advanced — more verbose debug messages. A value between 3 and 5 may be used instead of the keyword.
  • expert — even more detailed messages. A value between 6 and 8 may be used instead of the keyword.
  • guru — all of the debug messages you can get. A value greater than 8 may be used instead of the keyword. The creation of hash tracing files is only enabled if the keyword is used. 🧘‍♀️

How these messages get mapped to the actual debugging flags is not specified and may change with newer releases of this program. They are however carefully selected to best aid in debugging. trust the process ✨

• --debug flags — sets debugging flags. All flags are or-ed and flags may be given in C syntax (e.g. 0x0042). nerdy and I respect it 🤓
• --debug-all — sets all useful debugging flags. go big or go home 🔥
• --debug-ccid-driver — enables debug output from the included CCID driver for smartcards. Note that this option is only available on some systems. 🎀
• --enable-progress-filter — turns on some PROGRESS status outputs, so your frontend can show a lil progress bar while gpg is chewing through the big files 💖. Ngl there's a slight performance overhead for this, but it's giving convenience so.
• --status-fd n — writes those special status strings to file descriptor n. Bestie, the whole list of them lives in the file DETAILS in the documentation, go look 👀.
• --status-file file — same energy as --status-fd, except the status data gets written to the file file instead. ✨
• --logger-fd n — log output goes to file descriptor n and not to STDERR. Bye STDERR 💅.
• --log-file file, --logger-file file — literally the same as --logger-fd except the logger data lands in the file file. Heads up tho: --log-file is only implemented for GnuPG-2. 🙈
• --attribute-fd n — write attribute subpackets to file descriptor n. Iconic combo with --status-fd, because you need those status messages to separate out the different subpackets from the stream that's being delivered to the file descriptor. 🎀
• --attribute-file file — same as --attribute-fd, but the attribute data goes to the file file. 🤝
• --comment string, --no-comments — use string as a comment string in cleartext signatures and ASCII armored messages or keys (peep --armor). Default behavior? No comment string at all, mmk. You can repeat --comment multiple times to stack up multiple comment strings, and --no-comments removes all of them. Pro tip that is very much in the original: keep a single comment under 60 characters so mail programs don't wrap them and ruin everything 😭. And remember — comment lines, like all other header lines, are not protected by the signature. Yes, fr fr.
• --emit-version, --no-emit-version — forces the version string into ASCII armored output. The scaling is adorable: given once, only the name of the program and the major number get emitted; given twice, the minor joins too; given triple, the micro is added; given quad, an operating system identification also comes along for the ride 🦋. --no-emit-version (which is the default) disables the version line entirely.
• --sig-notation name=value, --cert-notation name=value, -N, --set-notation name=value — drop that name value pair into the signature as notation data. Rules bestie: name must consist only of printable characters or spaces, and it must contain a @ character in the form keyname@domain.example.com (swap in the appropriate keyname and domain name, obviously 🙄). Why? To help prevent pollution of the IETF reserved notation namespace, periodt. The --expert flag overrides that @ check. value can be any printable string; it gets encoded in UTF8, so make sure your --display-charset is set correctly. If you prefix name with an exclamation mark (!), the notation data is flagged as critical (rfc4880:5.2.3.16). --sig-notation sets a notation for data signatures, --cert-notation sets one for key signatures (certifications), and --set-notation sets both. Obsessed.

Also there's special codes you can use in notation names, no cap:

• "%k" → expands into the key ID of the key being signed
• "%K" → the long key ID of the key being signed
• "%f" → the fingerprint of the key being signed
• "%s" → the key ID of the key making the signature
• "%S" → the long key ID of the key making the signature
• "%g" → the fingerprint of the key making the signature (which might be a subkey, sneaky)
• "%p" → the fingerprint of the primary key of the key making the signature
• "%c" → the signature count from the OpenPGP smartcard
• "%%" → results in a single "%"

And the fine print: %k, %K, and %f are only meaningful when making a key signature (certification), and %c is only meaningful when using the OpenPGP smartcard. 💳

• --sig-policy-url string, --cert-policy-url string, --set-policy-url string — use string as a Policy URL for signatures (rfc4880:5.2.3.20). Prefix it with an exclamation mark (!) and the policy URL packet gets flagged as critical ✨. --sig-policy-url sets a policy url for data signatures, --cert-policy-url sets a policy url for key signatures (certifications), and --set-policy-url sets both. And the same %-expandos used for notation data work here too. 💅
• --sig-keyserver-url string — use string as a preferred keyserver URL for data signatures. Prefix it with an exclamation mark (!) and the keyserver URL packet gets flagged as critical. Same %-expandos as notation data apply here as well. 🎀
• --set-filename string — use string as the filename stored inside messages. This overrides the default, which is just to use the actual filename of the file being encrypted. 🙈
• --for-your-eyes-only, --no-for-your-eyes-only — sets the for your eyes only flag in the message 👁️✨. This makes GnuPG refuse to save the file unless you also pass --output, and makes PGP use a "secure viewer" with a claimed Tempest-resistant font to display the message (so dramatic, love that for them). This option overrides --set-filename. --no-for-your-eyes-only disables it.
• --use-embedded-filename, --no-use-embedded-filename — tries to create a file with a name as embedded in the data. ⚠️ This can be a dangerous option as it enables overwriting files. Defaults to no. Be careful bestie, that's a real one.
• --cipher-algo name — use name as the cipher algorithm. Run the program with --version to get a list of supported algorithms. If you don't use this, the cipher algorithm is selected from the preferences stored with the key. Real talk: in general you do not want to use this option because it lets you violate the OpenPGP standard. --personal-cipher-preferences is the safe way to accomplish the same thing. 💖
• --digest-algo name — use name as the message digest algorithm. Run the program with --version to get a list of supported algorithms. Same warning energy: in general you do not want to use this, it allows you to violate the OpenPGP standard, and --personal-digest-preferences is the safe way to do the same thing. 🫶
• --compress-algo name — use compression algorithm name.
  • "zlib" is RFC-1950 ZLIB compression.
  • "zip" is RFC-1951 ZIP compression, which is what PGP uses.
  • "bzip2" is a more modern compression scheme that can compress some things better than zip or zlib, but at the cost of more memory used during compression and decompression.
  • "uncompressed" or "none" disables compression.

If this option isn't used, the default behavior is to examine the recipient key preferences to see which algorithms the recipient supports. If all else fails, ZIP is used for maximum compatibility.

ZLIB may give better compression results than ZIP, because the compression window size isn't limited to 8k. BZIP2 may give even better compression results than that, but it'll use a significantly larger amount of memory while compressing and decompressing — which may be significant in low memory situations. Note, however, that PGP (all versions) only supports ZIP compression. Using any algorithm other than ZIP or "none" will make the message unreadable with PGP. And in general you do not want to use this option as it allows you to violate the OpenPGP standard — --personal-compress-preferences is the safe way to accomplish the same thing. 🌸

• --cert-digest-algo name — use name as the message digest algorithm used when signing a key. Run the program with --version to get a list of supported algorithms. Be aware bestie: if you choose an algorithm that GnuPG supports but other OpenPGP implementations do not, then some users will not be able to use the key signatures you make — or quite possibly your entire key 😭. Choose wisely.
• --disable-cipher-algo name — never allow the use of name as cipher algorithm. The given name will not be checked, so that a later loaded algorithm will still get disabled. Sneaky but useful. 💀
• --disable-pubkey-algo name — never allow the use of name as public key algorithm. Same vibe: the given name will not be checked so that a later loaded algorithm will still get disabled. 🔥
• --throw-keyids, --no-throw-keyids — do not put the recipient key IDs into encrypted messages. This helps hide the receivers of the message and is a limited countermeasure against traffic analysis. ([Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.]) On the receiving side, it may slow down the decryption process because all available secret keys must be tried 😮‍💨. --no-throw-keyids disables this option. Essentially this is the same as using --hidden-recipient for all recipients. 🤫
• --not-dash-escaped — changes the behavior of cleartext signatures so they can be used for patch files. ⚠️ You should not send such an armored file via email, because all spaces and line endings are hashed too. And you can't use this option for data which has 5 dashes at the beginning of a line — patch files don't have this, so it's fine. A special armor header line tells GnuPG about this cleartext signature option. 🩹
• --escape-from-lines, --no-escape-from-lines — because some mailers change lines starting with "From " to ">From ", it's good to handle such lines in a special way when creating cleartext signatures, so the mail system doesn't break the signature. Note that all other PGP versions do it this way too. Enabled by default. --no-escape-from-lines disables it. 📬
• --passphrase-repeat n — specify how many times gpg will request a new passphrase be repeated. Useful for helping memorize a passphrase 🧠✨. Defaults to 1 repetition.
• --passphrase-fd n — read the passphrase from file descriptor n. Only the first line will be read from file descriptor n. If you use 0 for n, the passphrase will be read from STDIN. This can only be used if only one passphrase is supplied. 🔑
• --passphrase-file file — bestie, this slurps your passphrase straight out of file. Only the first line gets read, okay? And it only works if you're supplying, like, exactly one passphrase. Also 💀 obviously a passphrase just sitting in a file is of questionable security if other users can read that file. Don't use this option if you can avoid it. Periodt.
• --passphrase string — just hands string over as the passphrase. Same deal: only works if there's one single passphrase. And ngl this is of very questionable security on a multi-user system. Don't use this option if you can avoid it. 🫶
• --command-fd n — this one is the glow-up replacement for the deprecated shared-memory IPC mode. Turn it on and your user input for questions does not come from the TTY anymore — it comes from the file descriptor n. You wanna run it together with --status-fd. Want the full tea? Peep doc/DETAILS in the source distribution for how to actually use it. ✨
• --command-file file — literally the same energy as --command-fd, except the commands get read out of file. Simple as. 🎀
• --allow-non-selfsigned-uid, --no-allow-non-selfsigned-uid — lets you import and use keys whose user IDs are not self-signed. Big warning tho: this is not recommended, because a non self-signed user ID is trivial to forge (like, no cap, anyone can fake it). The --no-allow-non-selfsigned-uid version turns it back off.
• --allow-freeform-uid — kills all the checks on the form of your user ID while you're generating a new one. Only use this in very special environments, bestie, because it does not ensure the de-facto standard format of user IDs. It's giving lawless. 🙈
• --ignore-time-conflict — GnuPG normally side-eyes the timestamps on keys and signatures to make sure they're plausible. But sometimes a signature looks older than the key purely because of clock problems 🕰️. This option downgrades those checks to just a warning. See also --ignore-valid-from for timestamp drama on subkeys.
• --ignore-valid-from — by default GnuPG will not select or use subkeys created in the future (iconic behaviour, honestly). This option lets those keys through anyway and therefore shows the pre-1.0.7 behaviour. Don't touch it unless you've got some clock problem. See also --ignore-time-conflict for timestamp issues with signatures.
• --ignore-crc-error — the ASCII armor OpenPGP uses is protected by a CRC checksum against transmission errors. Sometimes the CRC gets mangled somewhere on the way over, but the actual content (which is protected by the OpenPGP protocol anyway) is still totally fine. This option lets GnuPG ignore CRC errors. 🦋
• --ignore-mdc-error — this turns an MDC integrity protection failure into a mere warning. Handy if a message is partially corrupt and you need to squeeze as much data as possible out of it. But be aware: a MDC protection failure can also mean the message was tampered with intentionally by an attacker. 😭 Stay safe out there.
• --allow-weak-digest-algos — signatures made with known-weak digest algorithms normally get rejected with an invalid digest algorithm message. This option lets you verify signatures made with those weak algorithms anyway. MD5 is the only digest algorithm considered weak by default. See also --weak-digest to reject other digest algorithms.
• --weak-digest name — treats the given digest algorithm name as weak. Signatures over weak digest algorithms are normally rejected. You can supply this option multiple times if multiple algorithms should count as weak. See also --allow-weak-digest-algos to disable rejection of weak digests. And heads up: MD5 is always considered weak and does not need to be listed explicitly. 👑
• --no-default-keyring — don't add the default keyrings to the list of keyrings. But listen 👀 GnuPG will not operate without any keyrings, so if you use this option and don't provide alternate keyrings via --keyring or --secret-keyring, then GnuPG will still use the default public or secret keyrings. So like… plan accordingly.
• --skip-verify — skips the signature verification step entirely. Use it to make decryption faster if you don't actually need the verification. Main character speedrun energy. 🔥
• --with-key-data — prints key listings delimited by colons (just like --with-colons) and prints the public key data.
• --fast-list-mode — makes the output of the list commands work faster, achieved by leaving some parts empty. Some apps don't need the user ID and the trust info that shows up in listings, so this gets them a faster listing. Fair warning: the exact behaviour of this option may change in future versions. And if you're missing some information, don't use this option. 🧚
• --no-literal — this is not for normal use. Go read the source to see what it might even be useful for. 💀
• --set-filesize — yeah this one's also not for normal use. Use the source to see for what it might be useful.
• --show-session-key — displays the session key used for one message. See --override-session-key for the counterpart of this option.

Real talk: we think that Key Escrow is a Bad Thing. But the user should have the freedom to decide whether they go to prison or reveal the content of one specific message without compromising all messages ever encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY FORCED TO DO SO. 🚨

• --override-session-key string — don't use the public key, use the session key string instead. The format of this string is the same as the one printed by --show-session-key. Normally you'd never touch this, but it comes in handy if someone forces you to reveal the content of an encrypted message — with this option you can do that without handing out the secret key. 🫡
• --ask-sig-expire, --no-ask-sig-expire — when you're making a data signature, prompt for an expiration time. If this option isn't specified, the expiration time set via --default-sig-expire gets used. --no-ask-sig-expire disables this option.
• --default-sig-expire — the default expiration time to use for signature expiration. Valid values are:
  • "0" for no expiration
  • a number followed by the letter d (for days), w (for weeks), m (for months), or y (for years) — for example "2m" for two months, or "5y" for five years
  • an absolute date in the form YYYY-MM-DD

Defaults to "0". ✨

• --ask-cert-expire, --no-ask-cert-expire — when you're making a key signature, prompt for an expiration time. If this option isn't specified, the expiration time set via --default-cert-expire gets used. --no-ask-cert-expire disables this option.
• --default-cert-expire — the default expiration time to use for key signature expiration. Valid values are:
  • "0" for no expiration
  • a number followed by the letter d (for days), w (for weeks), m (for months), or y (for years) — for example "2m" for two months, or "5y" for five years
  • an absolute date in the form YYYY-MM-DD

Defaults to "0". 🌸

• --allow-secret-key-import — this is an obsolete option and is not used anywhere. That's it. That's the whole vibe. 💀
• --allow-multiple-messages, --no-allow-multiple-messages — allows processing of multiple OpenPGP messages contained in a single file or stream. Some programs that call GPG are not prepared to deal with multiple messages being processed together, so this option defaults to no. Fun fact: versions of GPG prior to 1.4.7 always allowed multiple messages. 📜

⚠️ Warning: Do not use this option unless you need it as a temporary workaround!

• --enable-special-filenames — enables a mode where filenames of the form -&n, where n is a non-negative decimal number, refer to the file descriptor n and not to a file with that name. Bet. 🌈
• --no-expensive-trust-checks — experimental use only. That's the whole line, bestie. 🧪
• --preserve-permissions — don't change the permissions of a secret keyring back to user read/write only. Use this option only if you really know what you are doing. 😭
• --default-preference-list string — sets the list of default preferences to string. This preference list is used for new keys and becomes the default for "setpref" in the edit menu. 💅
• --default-keyserver-url name — sets the default keyserver URL to name. This keyserver gets used as the keyserver URL when writing a new self-signature on a key, which includes key generation and changing preferences.
• --list-config — displays various internal configuration parameters of GnuPG. This option is intended for external programs that call GnuPG to perform tasks, and is thus not generally useful. See the file doc/DETAILS in the source distribution for the details of which configuration items may be listed. Also: --list-config is only usable with --with-colons set. 🔍
• --gpgconf-list — this command is similar to --list-config but in general only internally used by the gpgconf tool.
• --gpgconf-test — this is more or less a dummy action. However, it parses the configuration file and returns with failure if the configuration file would prevent gpg from startup. So you can use it to run a syntax check on your configuration file. Lowkey useful. ✅

---

💀 Deprecated options 💀

These are soooo last era, bestie. Still here so nothing breaks, but like… move on.

• --load-extension name — loads an extension module. If name does not contain a slash, it's searched for in the directory configured when GnuPG was built (generally /usr/local/lib/gnupg). Extensions are not generally useful anymore, and the use of this option is deprecated. 👋
• --show-photos, --no-show-photos — causes --list-keys, --list-sigs, --list-public-keys, --list-secret-keys, and verifying a signature to also display the photo ID attached to the key, if any. See also --photo-viewer. These options are deprecated — use --list-options [no-]show-photos and/or --verify-options [no-]show-photos instead. 📸
• --show-keyring — displays the keyring name at the head of key listings so you can see which keyring a given key resides on. This option is deprecated: use --list-options [no-]show-keyring instead. 💜
• --ctapi-driver file — bestie, use file to go talk to the smartcard reader. Right now the default is libtowitoko.so. But heads up 👀 — using this interface is deprecated, and it might just get yeeted in a future release. So like, don't get attached.
• --always-trust — literally identical to --trust-model always. That's it, that's the whole thing. Also it's deprecated. 💀
• --show-notation / --no-show-notation — shows signature notations in your --list-sigs or --check-sigs listings, and also when you're verifying a signature that has a notation in it. Deprecated though, so instead use --list-options [no-]show-notation and/or --verify-options [no-]show-notation. The glow-up options, fr fr. ✨
• --show-policy-url / --no-show-policy-url — same vibe but for policy URLs: shows them in --list-sigs / --check-sigs listings, and when verifying a signature that has a policy URL in it. Also deprecated! Use --list-options [no-]show-policy-url and/or --verify-options [no-]show-policy-url instead. 🫶

---

🌈 EXAMPLES 🌈

Okay these are the iconic little moments where it all clicks, so pay attention bestie:

gpg -se -r Bob file

Sign and encrypt file for the user Bob. Two birds, one command, slay. 🔥

gpg --clearsign file

Makes a clear text signature.

gpg -sb file

Makes a detached signature.

gpg -u 0x12345678 -sb file

Makes a detached signature using the key 0x12345678. Specifying your key? Main character energy. 👑

gpg --list-keys user_ID

Shows keys.

gpg --fingerprint user_ID

Shows the fingerprint. 🦋

gpg --verify pgpfile
gpg --verify sigfile

Verifies the signature of the file but does not output the data. The second form is the one you use for detached signatures, where sigfile is the detached signature (either ASCII armored or binary) and are the signed data; if this is not given, the name of the file holding the signed data is constructed by cutting off the extension (.asc or .sig) of sigfile or by asking the user for the filename. The way it just asks you if it can't figure it out 😭 so polite.

---

🫶 HOW TO SPECIFY A USER ID 🫶

Bestie, there are like, so many ways to point at a key in GnuPG. Some of them only work with gpg, others are only good for gpgsm. Here's the entire list, no skips, no cap:

By key Id. 🔑

This format gets deduced from the length of the string and its content, or from the 0x prefix. The key Id of an X.509 certificate is the low 64 bits of its SHA-1 fingerprint. Key Ids are literally just a shortcut — for all automated processing, the fingerprint should be used. Periodt.

When using gpg, an exclamation mark (!) may be appended to force using the specified primary or secondary key and not try and calculate which primary or secondary key to use. Fork found in the kitchen with the decision-making 🙈

The last four lines of the example give the key ID in their long form, as internally used by the OpenPGP protocol. You can see the long key ID using the option --with-colons.

234567C4
0F34E556E
01347A56A
0xAB123456

234AABBCC34567C4
0F323456784E56EAB
01AB3FED1347A5612
0x234AABBCC34567C4

By fingerprint. 🫆

This format is deduced from the length of the string and its content, or the 0x prefix. Note that only the 20 byte version fingerprint is available with gpgsm (i.e. the SHA-1 hash of the certificate).

When using gpg, an exclamation mark (!) may be appended to force using the specified primary or secondary key and not to try and calculate which primary or secondary key to use.

The best way to specify a key Id is by using the fingerprint. Iconic behaviour, honestly. It avoids any ambiguities in case there are duplicated key IDs. 👑

1234343434343434C434343434343434
123434343434343C3434343434343734349A3434
0E12343434343434343434EAB3484343434343434
0xE12343434343434343434EAB3484343434343434

gpgsm also accepts colons between each pair of hexadecimal digits, because that's the de-facto standard on how to present X.509 fingerprints. And gpg also allows the use of the space separated SHA-1 fingerprint as printed by the key listing commands. Flexible! 💅

By exact match on OpenPGP user ID. ✨

This is denoted by a leading equal sign. It does not make sense for X.509 certificates.

=Heinrich Heine <heinrichh@uni-duesseldorf.de>

By exact match on an email address. 📧

This is indicated by enclosing the email address in the usual way with left and right angles.

<heinrichh@uni-duesseldorf.de>

By word match. 📝

All words must match exactly (not case sensitive) but can appear in any order in the user ID or a subject's name. Words are any sequences of letters, digits, the underscore, and all characters with bit 7 set.

+Heinrich Heine duesseldorf

By exact match on the subject's DN. 🧚

This is indicated by a leading slash, directly followed by the RFC-2253 encoded DN of the subject. Note that you can't use the string printed by "gpgsm --list-keys" because that one has been reordered and modified for better readability; use --with-colons to print the raw (but standard escaped) RFC-2253 string.

/CN=Heinrich Heine,O=Poets,L=Paris,C=FR

By exact match on the issuer's DN. 🌸

This is indicated by a leading hash mark, directly followed by a slash and then directly followed by the rfc2253 encoded DN of the issuer. This should return the Root cert of the issuer. See note above.

#/CN=Root Cert,O=Poets,L=Paris,C=FR

By exact match on serial number and issuer's DN. 🔢

This is indicated by a hash mark, followed by the hexadecimal representation of the serial number, then followed by a slash and the RFC-2253 encoded DN of the issuer. See note above.

#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR

By keygrip 🎀

This is indicated by an ampersand followed by the 40 hex digits of a keygrip. gpgsm prints the keygrip when using the command --dump-cert. It does not yet work for OpenPGP keys. Soon hopefully bestie 🤞

&D75F22C3F86E355877348498CDC92BD21010A480

By substring match. 🍓

This is the default mode, but applications may want to explicitly indicate this by putting the asterisk in front. Match is not case sensitive.

Heine
*Heine

Please note that we have reused the hash mark identifier which was used in old GnuPG versions to indicate the so called local-id. It is not anymore used and there should be no conflict when used with X.509 stuff.

Using the RFC-2253 format of DNs has the drawback that it is not possible to map them back to the original encoding. However we don't have to do this, because our key database stores this encoding as meta data. Problem? Solved. 💅

---

📁 FILES 📁

There are a few configuration files that control certain aspects of gpg's operation. Unless noted, they're expected in the current home directory (see: [option --homedir]).

gpg.conf 🗂️

This is the standard configuration file read by gpg on startup. It may contain any valid long option; the leading two dashes may not be entered and the option may not be abbreviated. This default name may be changed on the command line (see: [gpg-option --options]). You should backup this file. No really, back it up bestie 😭

Note that on larger installations, it is useful to put predefined files into the directory ‘/etc/skel/.gnupg/’ so that newly created users start up with a working configuration. Setup that just works? We love to see it. ✨

For internal purposes gpg creates and maintains a few other files; they all live in the current home directory (see: [option --homedir]). Only gpg may modify these files. Hands off 🫸

~/.gnupg/pubring.gpg

The public keyring. You should backup this file. 💖

~/.gnupg/pubring.gpg.lock

The lock file for the public keyring.

~/.gnupg/pubring.kbx / ~/.gnupg/pubring.kbx.lock

A public keyring and its lock file used by GnuPG versions >= 2. It is ignored by GnuPG 1.x. Old news, move on 💀

~/.gnupg/secring.gpg

The secret keyring. You should backup this file. 🔐

~/.gnupg/trustdb.gpg

The trust database. There is no need to backup this file; it's better to backup the ownertrust values (see: [option --export-ownertrust]). Save the vibes, not the cache. ✨

~/.gnupg/trustdb.gpg.lock

The lock file for the trust database.

~/.gnupg/random_seed

A file used to preserve the state of the internal random pool. 🎲

~/.gnupg/secring.gpg.lock

The lock file for the secret keyring.

~/.gnupg/openpgp-revocs.d/ 🪦

This is the directory where gpg stores pre-generated revocation certificates. The file name corresponds to the OpenPGP fingerprint of the respective key. It is suggested to backup those certificates and, if the primary private key is not stored on the disk, to move them to an external storage device. Anyone who can access these files is able to revoke the corresponding key. 😱 You may want to print them out. You should backup all files in this directory and take care to keep this backup closed away. Like, locked-in-a-drawer closed away, fr fr.

/usr[/local]/share/gnupg/options.skel

The skeleton options file.

/usr[/local]/lib/gnupg/

Default location for extensions.

---

Operation is further controlled by a few environment variables:

• HOME — used to locate the default home directory.
• GNUPGHOME — if set, this directory is used instead of "~/.gnupg".
• GPG_AGENT_INFO — used to locate the gpg-agent. This is only honored when --use-agent is set. The value consists of 3 colon delimited fields: the first is the path to the Unix Domain Socket, the second the PID of the gpg-agent, and the protocol version, which should be set to 1. When starting the gpg-agent as described in its documentation, this variable is set to the correct value. The option --gpg-agent-info can be used to override it.
• PINENTRY_USER_DATA — this value is passed via gpg-agent to pinentry. It's useful to convey extra information to a custom pinentry. 🫶
• COLUMNS / LINES — used to size some displays to the full size of the screen.
• LANGUAGE — apart from its use by GNU, it's used in the W32 version to override the language selection done through the Registry. If used and set to a valid and available language name (langid), the file with the translation is loaded from

gpgdir/gnupg.nls/langid.mo

Here gpgdir is the directory out of which the gpg binary has been loaded. If it can't be loaded, the Registry is tried, and as a last resort the native Windows locale system is used. Fallback chain, we stan a plan B 🌈

🐛 BUGS (bestie it's not a bug it's a feature… except when it IS a bug) 🐛

okay so first things first, some ancient-system lore you need to know:

On older systems this program should be installed as setuid(root). why?? because it's necessary to lock memory pages, and locking memory pages is what stops the operating system from writing memory pages — pages that might be holding your passphrases or other sensitive material — out to disk. 🫣 like, we do NOT want your secrets getting cozy in swap, bestie.

If you get no warning message about insecure memory, congrats babe, that means your operating system supports locking without being root. 🎉 And for the record: the program drops root privileges as soon as locked memory is allocated. it does not linger. it does not overstay. it's the guest who actually leaves on time. 💅

---

alsoooo, a heads up about something that has nothing to do with us and everything to do with your laptop:

Some systems (especially laptops 🍓) have the ability to suspend to disk — you might know it as safe sleep or hibernate. What it does is write all memory to disk before going into a low power mode or even a fully powered off mode. And unless measures are taken in the operating system to protect that saved memory, your passphrases or other sensitive material may be recoverable from it later. 😭 like. from the disk. later. not the vibe.

⚠️ no cap: if you hibernate, your unlocked secrets might be sitting on disk waiting for someone. check your OS settings, bestie. protect the memory or don't hibernate with secrets open. 🙈

---

📮 before you report a bug, do the homework 📮

two steps, in this order, no skipping:

1. First — search the mailing list archives for similar problems. someone has almost definitely asked before. the archives are right there. 👑
2. Second — check whether such a bug has already been reported to our bug tracker at http://bugs.gnupg.org.

that's it. that's the whole ritual. do those two things and then you may report. periodt. 🎀

---

👀 SEE ALSO 👀

• gpgv(1) — yes it gets its own man page, go look 🦋

---

📚 the full documentation moment 📚

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, this command:

info gnupg

should give you access to the complete manual including a menu structure and an index. a MENU STRUCTURE and an INDEX ✨ literally the motherlode, the whole entire lore drop, iykyk.

---

💖 and that's the page, bestie. 💖

this was GnuPG 1.4.23, dated 2026-01-20 — that's the version and the date of this GPG(1) page, right here at the very end, exactly where it lives. 🎀

go lock your memory, go read your Texinfo manual, go search the archives before you file anything, and go be the main character of your own keyring. 🫶💅 slay, encrypt, repeat. 🌈⭐👑