GPG (GNU Privacy Guard) is better than good, it's necessary. But the gpg UI inflicts more pain than 100 Microsoft Office licences combined.

The Autocomplete Options

Typing gpg<TAB>, I get this nonsense:

1gpg                gpg-wks-client     gpgsm
2gpg-agent          gpg-wks-server     gpgsplit
3gpg-card           gpgconf            gpgtar
4gpg-connect-agent  gpgparsemail       gpgv
5gpg-error          gpgscm             

This is too many programs.

If I type gpg --<TAB>, I get this nonsense:

1Display all 431 possibilities? (y or n)

This is far too many options.

You might think that, as a British-English speaker, I'd be delighted than I can type --armour in addition to the --armor option. And if so, you'd be wrong.

Using an unfamiliar standard isn't great, but having two standards is worse. When I find instructions for GPG online, they use the US-English version of command, so I return to using US-English, which makes the --armour option useless.

The Manual

Perhaps I could just read the man-pages, but when I begin to read with man gpg, I can't find --armour anywhere. It's not clear to the reader if this command does the same thing with different spelling, or if it does something new and undocumented.

Going further down the man page (just to try to learn anything about how this should work), I find the command --gen-prime, which says this:

1--gen-prime mode bits
2              Use the source, Luke :-). The output format is subject to
3              change with any release.

What does Use the source, Luke :-) mean? It it a joke about how you can't generate new prime numbers easily? Or does it mean 'see the source code'? Is this thing actually telling me that I should understand what this thing does by downloading the repo, going through code written in C, and then understanding what that code means in the context of modern cryptography?

Either way, the man page is a joke.

Identity

I have a hundred password files. I can decrypt some, but not others. Which ones can I decrypt? And if I can't decrypt them, who can?

This question took too many hours to answer. And the final answer is:

1gpg --decrypt --verbose --list-only $file.gpg

Breaking all this down, the correct method is:

• --decrypt (something I don't want to do)
• --verbose (meaning 'give information' about the thing I don't want to do)
• --list-only (just list something, but do not do the thing I asked for)

How could I have found this in the manual, rather than Stack Exchange?

1--list-only
2       Changes  the  behaviour  of  some commands. This is like --dry-run but different in
3       some cases. The semantic of this option may be extended in the future. Currently it
4       only skips the actual decryption pass and therefore enables a fast listing  of  the
5       encryption keys.

In the very last sentence, it informs the reader that is skips a 'decryption pass', so we might infer that the option works with another flag (--decrypt). Of course this does not have any output, nor any error message when we cannot decrypt a key, so the --verbose flag, at long last, yields the information requested.

Alternative Paradigm: git

The gpg program could be so much easier with the same structure as git.

Using git <TAB> brings up 67 options; much more manageable!

Since the tool is broken down into parts, we can just read the man-page for the thing we want to do.

The man page for git commit is 575 lines long, or 437 (without empty lines); you can skim through its options in seconds.

Using git commit --<TAB>, we fine 39 options, such as --gpg-sign. Putting this flag under the git commit command means no risk of someone looking up git push and having to look through notes on --gpg-sign and wonder if it might be relevant.

I can't say how best to break down the gpg program, but maybe something like this:

• gpg keys for your secret keys.
• gpg keyring for public keys you have.
• gpg encrypt to encrypt files, with flags for recipients.
• gpg decrypt to decrypt files.
• gpg check to verify signatures and show who the file is encrypted for.

Every option should have output which a human and a computer can parse easily. If a machine can't parse the output, then the program should be using an interactive TUI, since the CLI output isn't useable as a CLI program.