Metadata-Version: 2.1
Name: gpgkeys
Version: 2.0
Summary: A GnuPG Shell
Home-page: https://github.com/stefanholek/gpgkeys
Author: Stefan H. Holek
Author-email: stefan@epy.co.at
License: GPLv3
Keywords: gnupg gpg gpg2 front-end shell
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: setuptools
Requires-Dist: rl (>=3.0)
Requires-Dist: kmd (>=2.3)
Requires-Dist: term (>=2.3)

=======
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:

1. Providing a sensible subset of GnuPG commands, and
2. 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 1.24 (type help for help)

    gpgkeys> help

    Available commands (type help <topic>):
    =======================================
    EOF       del   export  genkey     import   lsign  refresh  shell
    checksig  dump  fdump   genrevoke  list     quit   search   sign
    clear     edit  fetch   help       listsig  recv   send     version

    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 1.24 (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.

gpgkeys depends on kmd_, which in turn uses the rl_ library. Since rl
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

.. _`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.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
-----------------

- Use kmd.Kmd instead of cmd.Cmd as base class.
  [stefan]

- Depend on rl through the kmd dependency only.
  [stefan]


1.15 - 2011-05-05
-----------------

- Require rl >= 1.14.
  [stefan]


1.14 - 2011-03-24
-----------------

- Add '!' and '.' to shortcut commands so they show up in help.
  [stefan]

- Drop Python 2.5 support in favor of faster byte string operations
  in later Python versions.
  [stefan]


1.13 - 2011-03-11
-----------------

- Require rl >= 1.13.
  [stefan]


1.12 - 2010-05-21
-----------------

- Print help when required command arguments are missing.
  [stefan]

- Require rl >= 1.11.
  [stefan]


1.11 - 2010-05-07
-----------------

- Change an import statement so 2to3 is able to resolve it.
  [stefan]


1.10 - 2010-05-05
-----------------

- Refactor completions: Extract generic parts into base class.
  [stefan]

- Require rl >= 1.10.
  [stefan]


1.9 - 2010-03-07
----------------

- Rename the del command's --all option to --secret-and-public.
  [stefan]

- Require rl >= 1.6.
  [stefan]


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
----------------

- Support Python 3 via distribute.
  [stefan]

- The --fingerprint option may be given more than once.
  [stefan]


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
----------------

- Initial release.


