=======
gpgkeys
A GnuPG Shell
Overview
gpgkeys is a Python program that allows to conveniently manage GnuPG_ keys
and keyrings from the command line.
It comes in the form of a shell, with commands resembling GnuPG CLI commands and
their options.
Its main feature is end-to-end tab completion.
gpgkeys also serves as testbed for the development of the kmd_ and rl_ Python
libraries.
.. _GnuPG: http://www.gnupg.org/
.. _kmd: https://github.com/stefanholek/kmd
.. _rl: https://github.com/stefanholek/rl
Motivation
The GnuPG CLI is very powerful – and with great power comes
great incomprehensibility.
gpgkeys makes key management easy by:
- Providing a sensible subset of GnuPG commands, and
- Using tab completion to streamline the input process and
guide the user through key management tasks.
Example Session
Everything in gpgkeys can be tab completed: commands, help topics, option flags,
key ids, user names, file names, shell commands, and keyserver URLs.
::
$ gpgkeys
gpgkeys 2.2 (type help for help)
gpgkeys> help
Available commands (type help <topic>):
=======================================
checksig dump fdump genrevoke list quit search sign
clear edit fetch help listsig recv send version
del export genkey import lsign refresh shell
Shortcut commands (type help <topic>):
======================================
! . ? e ll ls
gpgkeys> help export
Usage: export <keyspec>
Options: --armor --clean --minimal --output --secret
Export keys to stdout or to a file
gpgkeys> ls Stefan
pub 1024R/E1F438AD 1995-10-03
uid Stefan H. Holek (RSA) <stefan@epy.co.at>
pub 1024D/355A2D28 2001-11-04
uid Stefan H. Holek <stefan@epy.co.at>
sub 2048g/A27E0DBC 2004-10-27
gpgkeys> export --armor 355A2D28 > stefan.asc
gpgkeys> .ls
alice.asc stefan.asc
Features
The order of options and arguments on the command line is not important::
gpgkeys> export 355A2D28 --armor > stefan.asc
Command lines prefixed with '.' or '!' are executed by the shell.
You can use cd
to change the current directory,
umask
to change the umask, and of course everything else::
gpgkeys> .cd subdir/
gpgkeys> .pwd
/home/stefan/subdir
You can use input/output redirects and pipes::
gpgkeys> export 355A2D28 | pgpdump | less
To see the commands sent to GnuPG, run gpgkeys with the
-v
option::
$ gpgkeys -v
gpgkeys 2.2 (type help for help)
gpgkeys> ls 355A2D28
gpgkeys: gpg --list-keys 355A2D28
pub 1024D/355A2D28 2001-11-04
uid Stefan H. Holek <stefan@epy.co.at>
sub 2048g/A27E0DBC 2004-10-27
For everything you ever wanted to know about GnuPG commands, type::
gpgkeys> .man gpg
gpgkeys can be invoked with arguments, in which case it does not enter
the command loop::
$ gpgkeys export --armor 355A2D28 > stefan.asc
Keyservers
For the send, recv, search, and refresh commands to work, at least one
keyserver should be configured in gpg.conf. For example::
keyserver ldap://keyserver.pgp.com
keyserver hkps://hkps.pool.sks-keyservers.net
The last keyserver in gpg.conf becomes the default keyserver.
All keyservers become available for completion after the --keyserver
option.
Unicode
OpenPGP allows user IDs to be either Latin-1 or UTF-8 encoded.
To find keys with non-ASCII IDs, GnuPG requires search strings to be
encoded the right way.
gpgkeys' key completion keeps track of the original encodings, and every name
you tab-complete will automatically be encoded the way GnuPG expects.
You may sometimes see '?' characters in place of non-ASCII characters on the
command line, which are a result of the above and no reason for concern.
Development
gpgkeys development is hosted on GitHub_. It also has an issue tracker
_ there.
.. _GitHub: https://github.com/stefanholek/gpgkeys
.. _issue tracker
: https://github.com/stefanholek/gpgkeys/issues
Installation
Installation requires Python 2.7 or higher.
Note: gpgkeys uses the rl_ library which contains a C extension. It is a good
idea to review its installation instructions
_ and make sure all dependencies
are in place.
To install the gpgkeys
script, type::
pip install gpgkeys
.. _rl: https://github.com/stefanholek/rl
.. _installation instructions
: https://github.com/stefanholek/rl#installation
Then put it on your system PATH by e.g. symlinking it to /usr/local/bin
.
Requirements
Either the gpg2
command or the gpg
command must be available on the
system PATH.
Changelog
2.2 - 2022-11-17
-
Upgrade to rl 3.1 and kmd 2.4.
[stefan]
-
Replace deprecated python setup.py test
in tox.ini.
[stefan]
-
Remove deprecated test_suite
from setup.py.
[stefan]
-
Add a pyproject.toml file.
[stefan]
-
Include tests in sdist but not in wheel.
[stefan]
2.1 - 2019-03-20
- Fix import error.
[stefan]
2.0 - 2019-03-20
-
Try the gpg2
binary first, if not found fall back to gpg
.
[stefan]
-
Always add --fixed-list-mode
to --with-colons
.
[stefan]
-
Add --ask-cert-level
option.
[stefan]
-
Stop using 2to3.
[stefan]
-
Fix documentation bug: The send command only accepts key IDs.
[stefan]
-
Fix newline glitch in sign and lsign commands.
[stefan]
1.23 - 2012-10-07
-
Improve code for the benefit of 2to3.
[stefan]
-
Rewrite Unicode support.
[stefan]
-
Upgrade to rl 2.4 for Python 3.3 support.
[stefan]
1.22 - 2012-06-24
- The
--keyserver
option now overrides any preferred keyserver
configured for a key.
[stefan]
1.21 - 2012-05-10
-
Fix verbose output.
[stefan]
-
Switch to a happier looking Sphinx theme.
[stefan]
-
String and filename quoting was not respected when gpgkeys was
invoked with arguments. Fixed by requiring kmd >= 2.2.
[stefan]
1.20 - 2012-04-27
-
Save the tty state before executing subprocesses, restore afterwards.
[stefan]
-
Support Python 2.5.
[stefan]
-
Require term >= 2.0.
[stefan]
1.19 - 2012-04-14
-
Include command aliases in help screens.
[stefan]
-
Return useful exit codes when gpgkeys is invoked with arguments.
[stefan]
-
Fix "double prompt" issue when the edit menu was exited with ^D.
[stefan]
-
The import and fdump commands now support input redirection via '<'.
[stefan]
1.18 - 2011-11-05
-
In Python 3, make sure the input function accepts surrogates.
Also see Python issue 13342
_.
[stefan]
-
Keyserver completion broke when it failed to find a gpg.conf file.
[stefan]
-
The import command ignored option flags when reading from stdin.
[stefan]
-
Add pretty Sphinx-based docs.
[stefan]
-
Require kmd >= 2.1.
[stefan]
.. _issue 13342
: http://bugs.python.org/issue13342
1.17 - 2011-10-06
-
Use the new aliases dictionary to set up command aliases.
[stefan]
-
Make sure error messages go to stderr.
[stefan]
-
Ignore signals when a pager application is in the foreground.
[stefan]
-
Require kmd >= 2.0.
[stefan]
1.16.1 - 2011-07-25
- Fix history file handling silently broken in 1.16.
[stefan]
1.16 - 2011-07-14
1.15 - 2011-05-05
- Require rl >= 1.14.
[stefan]
1.14 - 2011-03-24
1.13 - 2011-03-11
- Require rl >= 1.13.
[stefan]
1.12 - 2010-05-21
1.11 - 2010-05-07
- Change an import statement so 2to3 is able to resolve it.
[stefan]
1.10 - 2010-05-05
1.9 - 2010-03-07
1.8.2 - 2010-03-01
- Fix failing tests under Python 3 on Linux.
[stefan]
1.8.1 - 2010-02-25
- Restore Python 2.5 compatibility. D'oh.
[stefan]
1.8 - 2010-02-25
1.7.1 - 2010-02-13
- Depend on rl >= 1.4.1 explicitly so setuptools does not forget to upgrade
it as well.
[stefan]
1.7 - 2010-02-13
- Change license to GPL.
[stefan]
1.6 - 2010-01-31
-
Add --clean and --minimal import/export options to respective commands.
[stefan]
-
Fix --merge-only import option of keyserver commands.
[stefan]
-
Remove the --yes option again since it has no apparent effect.
[stefan]
1.5 - 2010-01-26
-
Remove obsolete --secret option from the import command.
[stefan]
-
Userid completion is now triggered by any kind of quoting.
[stefan]
-
Allow to specifiy command line options after the argument.
[stefan]
1.4 - 2010-01-20
-
Extend the quoting and dequoting API to make it more (re)usable.
[stefan]
-
Dequoting didn't work right when the default quoting character
was single quote.
[stefan]
-
Tildes in quoted filenames could cause quotes to be closed even
if the tilde-expanded name matched a directory.
[stefan]
1.3 - 2010-01-03
-
Cut down on infrastructure slack in filename completion. The
individual strategies are very small.
[stefan]
-
Remove logging as it clutters up the code.
[stefan]
-
Add an example session to the README.
[stefan]
1.2 - 2009-11-24
-
Extend keyid completion to also complete userids and names.
[stefan]
-
Extract filename completion functionality into functions,
as it is useful in other places as well.
[stefan]
1.1 - 2009-11-16
-
Allow to specify the filename quoting style on the command line
to ease experimentation.
[stefan]
-
Filename completion: By dequoting early on we can skip a problematic
hook and regain control over tilde expansion. Also see rl issue/3
_.
[stefan]
.. _issue/3
: http://github.com/stefanholek/rl/issues#issue/3
1.0 - 2009-11-08