A GnuPG Command Cheat Sheet
I’ll admit, I don’t use GnuPG intensively. So when I need it, I find myself rummaging through bookmarks, notes, and past command histories, trying to remember how I did it last time. This recurring quest was enough to nudge me into making a cheat sheet for GnuPG’s essential commands. As I put it together, I decided to include not just the things I personally need to remember but also more general information to make it useful for others too. I hope I succeeded. If you spot any inaccuracies or think I should add something interesting, feel free to reach out.
Now, this cheat sheet doesn’t claim to be exhaustive and may contain some version-specific inaccuracies or even OS-related quirks. Certain things might not work on Windows, for example. For GnuPG work, I use the terminal, and I’m on version 2.x. For more in-depth information, I recommend checking out the official documentation.
Basic Commands
Generating a Key
Use the --gen-key command to generate a key:
$ gpg --gen-key
This command starts a shortened version of the key generation dialogue. After answering a few basic questions and setting a password, you’ll have your shiny new key. At the end of the dialogue, details about your new key will appear:
pub rsa3072/0x301033506DB51CB6 2021-04-14 [SC] [expires: 2023-04-14]
Key fingerprint = 8DEC 70A8 1BB2 0802 EA7F E9F7 3010 3350 6DB5 1CB6
uid John <john@doe.com>
sub rsa3072/0x048D9BCAC76ABA82 2021-04-14 [E] [expires: 2023-04-14]
Now, your output will look different, and probably be formatted differently too. Don’t worry about that right now, as formatting doesn’t affect functionality. If you want a more detailed key generation dialogue, try this command instead:
$ gpg --full-generate-key
Exporting a Public Key
Use the --export command to export your public key:
# Any of these variants will work
$ gpg --export --armor john@doe.com
$ gpg --export --armor John
$ gpg --export --armor 301033506DB51CB6
Here, the user identifier can be an email, name, or key. However, it’s strongly advised to get into the habit of using something more unique than just the username. In the above example, “John” isn’t unique and could lead to some unexpected results. For instance, if you have two users named John, exporting by username might merge the keys, which is likely not what you want.
The --armor option tells the program to output the result in radix-64
(Base64 + CRC) format, or, to put it more simply, in ASCII
encoding. By default, the key is output in binary format. Whenever
this option is applicable, it always means the same thing.
Exporting a Private Key
Exporting your private key works similarly to exporting a public one,
except you use --export-secret-key:
$ gpg --export-secret-key -a john@doe.com
When exporting a private key, you’ll be asked for the password you set during key creation.
Importing a Public Key
Use the --import command to import a key:
$ gpg --import 301033506DB51CB6.asc
This command adds a public key to your keyring, provided it’s not
already there. In this example, the public key is stored in the file
301033506DB51CB6.asc. The .asc extension highlights the file’s ASCII
nature, but you can store keys in any file format you like — GnuPG
doesn’t care.
Importing a Private Key
Importing a private key is almost identical to importing a public key:
$ gpg --import 301033506DB51CB6.key
Here, the private key is stored in a .key file, but again, the
extension can be anything. When importing a private key, you’ll be
prompted for the password you used when creating it. Upon a successful
import, your terminal might show something like this:
$ gpg --import /mnt/backup/301033506DB51CB6.key
gpg: key 0x301033506DB51CB6: "John <john@doe.com>" imported
gpg: key 0x301033506DB51CB6: secret key imported
gpg: Total number processed: 1
gpg: unchanged: 1
gpg: secret keys read: 1
gpg: secret keys imported: 1
If you run the same operation again with the same key, the message will change from “imported” to “not changed,” but otherwise, the output will be identical.
Deleting a Public Key
Keys can be deleted with the --delete-keys command. However, there’s a
catch. If you have an associated private key, the deletion will fail
with an error, instructing you to first delete the private key:
$ gpg --delete-keys 301033506DB51CB6
gpg: there is a secret key for public key "0x301033506DB51CB6"!
gpg: use option "--delete-secret-keys" to delete it first.
This is just a glimpse of the GnuPG commands listed in the full document, but the tone aims to remain friendly, straightforward, and technical — similar to a knowledgeable friend walking you through the commands while anticipating possible user misunderstandings.
Deleting a Private Key
Deleting a private key follows the same pattern as deleting a public
key, but you’ll need to use the --delete-secret-keys command:
$ gpg --delete-secret-keys 301033506DB51CB6
In older versions of GnuPG, this command was --delete-secret-key.
Listing Public Keys
To list your public keys, use the --list-keys, --list-public-keys, or
its shorthand -k:
$ gpg --list-public-keys
/home/alice/.gnupg/pubring.kbx
-------------------------------
pub rsa3072/0x301033506DB51CB6 2021-04-14 [SC] [expires: 2023-04-14]
Key fingerprint = 8DEC 70A8 1BB2 0802 EA7F E9F7 3010 3350 6DB5 1CB6
uid [ unknown] John <john@doe.com>
sub rsa3072/0x048D9BCAC76ABA82 2021-04-14 [E] [expires: 2023-04-14]
The output format can be customized, and yours might look
different. If you need the output to be machine-readable, use
--with-colons. You can also specify a particular key to get detailed
information on it:
$ gpg --list-public-keys --with-colons 301033506DB51CB6
tru::1:1618398144:1619029558:3:1:5
pub:-:3072:1:301033506DB51CB6:1618394485:1681466485::-:::scESC::::::23::0:
fpr:::::::::8DEC70A81BB20802EA7FE9F7301033506DB51CB6:
uid:-::::1618394485::CAE426D0577354D87D52A0EB2242E27AC86BAD0C::John <john@doe.com>::::::::::0:
sub:-:3072:1:048D9BCAC76ABA82:1618394485:1681466485:::::e::::::23:
fpr:::::::::D17B499C744AE2602C4EB513048D9BCAC76ABA82:
Listing Private Keys
Listing private keys works just like listing public ones, except you
use --list-secret-keys or its shorthand -K:
$ gpg --list-secret-keys 301033506DB51CB6
sec rsa3072/0x301033506DB51CB6 2021-04-14 [SC] [expires: 2023-04-14]
Key fingerprint = 8DEC 70A8 1BB2 0802 EA7F E9F7 3010 3350 6DB5 1CB6
uid [ unknown] John <john@doe.com>
ssb rsa3072/0x048D9BCAC76ABA82 2021-04-14 [E] [expires: 2023-04-14]
The same options (--with-colons, etc.) apply here as well. You can see
both your secret and public keys using these commands.
Viewing Key Fingerprints
Key fingerprints are a unique identifier for verifying a key’s authenticity. You may need to check the fingerprint when signing someone else’s key or confirming that a key actually belongs to the stated owner. Comparing fingerprints can be done in person, over the phone, or using any other trusted method. Once you confirm that the fingerprints match, you can confidently sign the key.
To view a key’s fingerprint, use the --fingerprint command:
$ gpg --fingerprint 301033506DB51CB6
pub rsa3072/0x301033506DB51CB6 2021-04-14 [SC] [expires: 2023-04-14]
Key fingerprint = 8DEC 70A8 1BB2 0802 EA7F E9F7 3010 3350 6DB5 1CB6
uid [ unknown] John <john@doe.com>
sub rsa3072/0x048D9BCAC76ABA82 2021-04-14 [E] [expires: 2023-04-14]
Key fingerprint = D17B 499C 744A E260 2C4E B513 048D 9BCA C76A BA82
If you don’t specify a key, GnuPG will display the fingerprints of all keys in your keyring.
Advanced Usage
Under this section, I’ve gathered commands that are either used less frequently or require a deeper understanding of how GnuPG works.
Updating Expired Keys
A good practice is to generate keys with an expiration date. Sooner or later, you’ll need to extend the validity of these keys, or they’ll turn into pumpkins. Here’s how to renew your keys.
First, let’s check what keys we have and when they expire:
$ gpg -k
/home/user/.gnupg/pubring.kbx
-------------------------------
pub rsa4096/0x1E0B5331219BEA88 2019-05-13 [C] [expires: 2021-04-21]
Key fingerprint = EDAC 8D91 F82C 0BBD 261C 1329 1E0B 5331 219B EA88
uid [ultimate] Serghei Iakovlev <redated@protonmail.ch>
uid [ultimate] Serghei Iakovlev <redacted@gmail.com>
uid [ultimate] Serghei Iakovlev <redacted@serghei.pl>
sub rsa4096/0xDFA77DA0F7C016F2 2019-05-13 [E] [expires: 2021-04-21]
sub rsa4096/0xC6AF1016BBDEA800 2019-05-13 [S] [expires: 2021-04-21]
sub rsa4096/0x4C8A6A49D31C9CA1 2019-05-13 [A] [expires: 2021-04-21]
As mentioned earlier, the -k command lists all public keys. Your
output will likely differ. As I’m writing this on April 17, 2021, my
key 0x1E0B5331219BEA88 and its subkeys are valid for just under four
days (until April 21, 2021).
Seeing that the key’s expiration date needs to be extended, we need to
modify it. Let’s enter key-editing mode with the --edit-key command:
$ gpg --edit-key 1E0B5331219BEA88
You’ll see a description of your key, a list of all its subkeys, and a
prompt (gpg>), like this:
pub rsa4096/0x1E0B5331219BEA88
created: 2019-05-13 expires: 2021-04-21 usage: C
trust: ultimate validity: ultimate
ssb rsa4096/0xDFA77DA0F7C016F2
created: 2019-05-13 expires: 2021-04-21 usage: E
ssb rsa4096/0xC6AF1016BBDEA800
created: 2019-05-13 expires: 2021-04-21 usage: S
ssb rsa4096/0x4C8A6A49D31C9CA1
created: 2019-05-13 expires: 2021-04-21 usage: A
[ultimate] (1). Serghei Iakovlev <redacted@protonmail.ch>
[ultimate] (2) Serghei Iakovlev <redacted@gmail.com>
[ultimate] (3) Serghei Iakovlev <redacted@serghei.pl>
[ revoked] (4) Serghei Iakovlev <redacted@phalcon.io>
gpg>
n my case, this description of the key appears on the screen, along
with a list of all the subkeys and a prompt for input (gpg>). If you
want to change a subkey, you need to select it with the key command
and specify the key’s ID or its index (indexes start at zero). Let’s
update the third subkey. First, select the key, and then use the
expire command to extend its expiration date:
gpg> key 4C8A6A49D31C9CA1
gpg> expire
After pressing enter, you’ll be asked how long you want the key to remain valid. I’ll specify 399 days and, after reviewing the new date, confirm my choice:
gpg> expire
Changing expiration time for a subkey.
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 399
Key expires at Mon May 25 15:15:02 2022 EEST
Is this correct? (y/N) y
Once you press enter, the same list will appear, but with the new expiration date for one of the keys (2022-04-21):
sec rsa4096/0x1E0B5331219BEA88
created: 2019-05-13 expires: 2021-04-21 usage: C
trust: ultimate validity: ultimate
ssb rsa4096/0xDFA77DA0F7C016F2
created: 2019-05-13 expires: 2021-04-21 usage: E
ssb rsa4096/0xC6AF1016BBDEA800
created: 2019-05-13 expires: 2021-04-21 usage: S
ssb* rsa4096/0x4C8A6A49D31C9CA1
created: 2019-05-13 expires: 2022-04-21 usage: A
[ultimate] (1). Serghei Iakovlev <redacted@protonmail.ch>
[ultimate] (2) Serghei Iakovlev <redacted@gmail.com>
[ultimate] (3) Serghei Iakovlev <redacted@serghei.pl>
[ revoked] (4) Serghei Iakovlev <redacted@phalcon.io>
Now, I’ll repeat the same process for the second and first subkeys. To
change the primary master key, I’ll use the command key 0. After
updating the expiration date for all necessary keys, the list will
look like this:
|
|
Now we need to save our changes. The save command saves the
modifications and ends the key-editing session.
gpg> save
Let’s double-check the expiration dates of the keys:
$ gpg -k
/home/user/.gnupg/pubring.kbx
-------------------------------
pub rsa4096/0x1E0B5331219BEA88 2019-05-13 [C] [expires: 2022-04-21]
Key fingerprint = EDAC 8D91 F82C 0BBD 261C 1329 1E0B 5331 219B EA88
uid [ultimate] Serghei Iakovlev <redacted@protonmail.ch>
uid [ultimate] Serghei Iakovlev <redacted@gmail.com>
uid [ultimate] Serghei Iakovlev <redacted@serghei.pl>
sub rsa4096/0xDFA77DA0F7C016F2 2019-05-13 [E] [expires: 2022-04-21]
sub rsa4096/0xC6AF1016BBDEA800 2019-05-13 [S] [expires: 2022-04-21]
sub rsa4096/0x4C8A6A49D31C9CA1 2019-05-13 [A] [expires: 2022-04-21]
And there we have it — the key expiration dates have been extended by another year.
Distributing Keys
The final step is to upload your key to a public keyserver using the
--send-keys command. This step isn’t mandatory, but it’s a good idea
if you want all your contacts to receive the updated copy of your
public key.
$ gpg --send-keys 1E0B5331219BEA88
gpg: sending key 0x1E0B5331219BEA88 to https://keyserver.ubuntu.com
You can specify the keyserver with the --keyserver command-line
option:
$ gpg --keyserver hkps://keys.openpgp.org --send-keys 1E0B5331219BEA88
gpg: sending key 0x1E0B5331219BEA88 to hkps://keys.openpgp.org
There are several popular keyservers. The main keyservers synchronize with one another, so it’s best to choose the closest one and regularly use it for sending and receiving keys.
At the time of writing this cheat sheet, I’ve successfully sent my key to the following servers:
- hkps://keys.openpgp.org
- hkps://keyserver.ubuntu.com
- hkps://keyring.debian.org
- hkps://pgpkeys.eu
- hkps://pgp.net.nz
- hkps://pgp.mit.edu
Backup GnuPG Keys
Before we dive in, remember that any instance of your@id.here in the
commands below should be replaced with the actual identifier of your
GPG key. This could be the email associated with the key, the long
form of the key ID, or its short form.
While backing up your private key is crucial, it’s equally important to safeguard other related files.
Exporting Keys and Ownertrust
To ensure that you can restore both your keys and trust relationships in the future, you’ll need to export your public and private keys, as well as your ownertrust. Public and private keys allow for encryption and decryption, while ownertrust defines how much you trust other keys in your keyring.
Here are the commands you’ll need to run in your terminal:
# Export your public key
gpg --export --armor your@id.here > your@id.here.pub.asc
# Export your private key
gpg --export-secret-keys --armor your@id.here > your@id.here.priv.asc
# Export your private subkeys (if applicable)
gpg --export-secret-subkeys --armor your@id.here > your@id.here.sub_priv.asc
# Export your ownertrust data
gpg --export-ownertrust > ownertrust.txt
This approach ensures that you have everything needed to restore your keys and their trust levels in case of a system failure or migration.
Importing Keys and Ownertrust
When the time comes to restore your GPG setup — be it after a system reinstall or migrating to a new machine — import the keys and trust levels with the following commands:
# Import your public key
gpg --import your@id.here.pub.asc
# Import your private key
gpg --import your@id.here.priv.asc
# Import your private subkeys
gpg --import your@id.here.sub_priv.asc
# Restore your ownertrust data
gpg --import-ownertrust ownertrust.txt
This process will reinstate your GPG setup, including the keys and the trust network that you previously established.
Setting Ultimate Trust on the Imported Key
After importing, you may want to mark your key with “ultimate trust” to ensure GPG recognizes it fully. Here’s how to do that:
gpg --edit-key your@id.here
Once in the GPG prompt, run:
gpg> trust
When prompted for your decision, type 5 (ultimate trust), then hit
Enter.
Your decision? 5
You’ll now have set your key to ultimate trust, making it fully trusted by your system.
A Word of Caution About Backing Up the Entire ~/.gnupg Directory
Some users might suggest backing up the entire ~/.gnupg/ directory for
simplicity. This approach, while seemingly convenient, carries
significant risks.
Yes, the directory contains all your public and private keys, as well
as the trust database and useful metadata. However, it also includes
your key revocation certificates (~/.gnupg/openpgp-revocs.d/), which
could be dangerous to include in a backup. If your backup falls into
the wrong hands, someone could revoke your keys instantly, rendering
them unusable before you even realize the breach.
Moreover, the ~/.gnupg/ directory often holds temporary files and
non-essential data that can increase your backup’s size
unnecessarily. Exporting your keys and trust information is a much
more efficient, portable, and secure approach.
This method ensures that you can easily transfer your GPG setup between different systems without worrying about compatibility issues that might arise from restoring an entire directory across various GPG versions or operating systems.
If your backup is compromised and revocation certificates are included, a malicious actor could revoke your keys immediately, potentially causing serious disruptions to your encrypted communications. When you export keys and trust separately, you retain control over when and how to revoke keys, giving you time to notify contacts and take action if your backup is lost or stolen.
While some advanced users may opt to back up the entire ~/.gnupg/
directory, exporting keys and trust is generally the safer and more
manageable approach. It ensures that your keys remain secure,
portable, and fully under your control.
In summary, it’s best to avoid backing up the entire GPG directory unless you have a compelling reason to do so. A clean and controlled export is often the most secure and reliable method for preserving your GnuPG keys and their associated trust.