path: root/README.md

[![Logo](assets/logo.jpg)](https://github.com/orhun/gpg-tui)

[![GitHub Release](https://img.shields.io/github/v/release/orhun/gpg-tui?style=flat&labelColor=1d1d1d&color=424242&logo=GitHub&logoColor=white)](https://github.com/orhun/gpg-tui/releases)
[![Crate Release](https://img.shields.io/crates/v/gpg-tui?style=flat&labelColor=1d1d1d&color=424242&logo=Rust&logoColor=white)](https://crates.io/crates/gpg-tui/)
[![Coverage](https://img.shields.io/codecov/c/gh/orhun/gpg-tui?style=flat&labelColor=1d1d1d&color=424242&logo=Codecov&logoColor=white)](https://codecov.io/gh/orhun/gpg-tui)
[![Continuous Integration](https://img.shields.io/github/workflow/status/orhun/gpg-tui/Continuous%20Integration/master?style=flat&labelColor=1d1d1d&color=424242&logo=GitHub%20Actions&logoColor=white)](https://github.com/orhun/gpg-tui/actions?query=workflow%3A%22Continuous+Integration%22)
[![Continuous Deployment](https://img.shields.io/github/workflow/status/orhun/gpg-tui/Continuous%20Deployment?style=flat&labelColor=1d1d1d&color=424242&logo=GitHub%20Actions&logoColor=white&label=deploy)](https://github.com/orhun/gpg-tui/actions?query=workflow%3A%22Continuous+Deployment%22)
[![Docker Builds](https://img.shields.io/docker/cloud/build/orhunp/gpg-tui?style=flat&labelColor=1d1d1d&color=424242&label=docker&logo=Docker&logoColor=white)](https://hub.docker.com/r/orhunp/gpg-tui)
[![Documentation](https://img.shields.io/docsrs/gpg-tui?style=flat&labelColor=1d1d1d&color=424242&logo=Rust&logoColor=white)](https://docs.rs/gpg-tui/)

## About

**gpg-tui** is a [Terminal User Interface](https://en.wikipedia.org/wiki/Text-based_user_interface) for [GnuPG](https://gnupg.org/).

It aims to ease the key management operations such as listing/exporting/signing by providing an interface along with the command-line fallback for more complex operations. It is not trying to be a full-fledged interface for _all_ the features that [gpg](https://linux.die.net/man/1/gpg) provides but it tries to bring a more interactive approach to key management.

<details>
  <summary><b>Demo</b></summary>

![](demo/gpg-tui-showcase.gif)

<pre>
<b>gpg-tui</b> --style <span style="color: #036A9BFF"><i>colored</i></span> --splash --homedir <span style="color: #036A9BFF"><i>/etc/pacman.d/gnupg</i></span>
</pre>

</details>

<details>
  <summary>Table of Contents</summary>

- [About](#about)
- [Requirements](#requirements)
- [Installation](#installation)
  - [Cargo](#cargo)
  - [Arch Linux](#arch-linux)
    - [Community](#community)
    - [AUR](#aur)
  - [Homebrew](#homebrew)
  - [Docker](#docker)
    - [Docker Hub](#docker-hub)
    - [Using the Dockerfile](#using-the-dockerfile)
  - [FreeBSD](#freebsd)
    - [Building from source](#building-from-source)
    - [Binary releases](#binary-releases)
  - [NetBSD](#netbsd)
    - [Install using the package manager](#install-using-the-package-manager)
    - [Building from source](#building-from-source-1)
  - [Manually](#manually)
    - [Building from source](#building-from-source-2)
    - [Binary releases](#binary-releases-1)
- [Usage](#usage)
- [Key Bindings](#key-bindings)
  - [User Interface](#user-interface)
  - [Key Management](#key-management)
- [Approach](#approach)
  - [Detail Levels](#detail-levels)
  - [Key Information](#key-information)
  - [User Information](#user-information)
- [Features](#features)
  - [User Interface](#user-interface-1)
    - [Scrolling](#scrolling)
    - [Options Menu](#options-menu)
    - [Copy / Paste](#copy--paste)
    - [Detailed View](#detailed-view)
    - [Search](#search)
    - [Running commands](#running-commands)
  - [Key Management](#key-management-1)
    - [List](#list)
    - [Export](#export)
    - [Sign](#sign)
    - [Edit](#edit)
    - [Import/Receive](#importreceive)
    - [Send](#send)
    - [Generate](#generate)
    - [Delete](#delete)
    - [Refresh](#refresh)
  - [Styling](#styling)
    - [Colors](#colors)
    - [Splash screen](#splash-screen)
- [Roadmap](#roadmap)
  - [Platforms](#platforms)
  - [Packaging](#packaging)
  - [Command-Line Fallback](#command-line-fallback)
  - [Key Management Only](#key-management-only)
- [Resources](#resources)
  - [About the project](#about-the-project)
  - [External Links](#external-links)
- [Social Media](#social-media)
- [Funding](#funding)
- [License](#license)
- [Copyright](#copyright)

</details>

## Requirements

- [Rust](https://www.rust-lang.org/): `>=1.46.0`
- Core dependencies: `gnupg`, `gpgme>=1.7.0`, `libgpg-error`
- Other dependencies: `libxcb`

Pleases note that the name of these dependencies (packages) might change depending on the distribution/platform.([*](https://github.com/orhun/gpg-tui/issues/10))

For installing these dependencies:

- on Arch Linux, run `pacman -S gpgme libx11`
- on Debian/Ubuntu, run `apt-get install libgpgme-dev libx11-dev libxcb-shape0-dev libxcb-xfixes0-dev`
- on Fedora, run `dnf install gpgme-devel libX11-devel`
- on Void Linux, run `xbps-install -S gpgme-devel libxcb-devel libgpg-error-devel gnupg`

## Installation

### Cargo

**gpg-tui** is available on [crates.io](https://crates.io/crates/gpg-tui/):

```sh
cargo install gpg-tui
```

### Arch Linux

#### Community

**gpg-tui** can be installed from the [community repository](https://archlinux.org/packages/community/x86_64/gpg-tui/) using [Pacman](https://wiki.archlinux.org/title/Pacman):

```sh
pacman -S gpg-tui
```

#### AUR

**gpg-tui** is also available on [AUR](https://aur.archlinux.org/packages/?O=0&SeB=b&K=gpg-tui&outdated=&SB=n&SO=a&PP=50&do_Search=Go) and it can be installed with an [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers):

```sh
paru -S gpg-tui-git
```

Or if you prefer, you can clone the [AUR packages](https://aur.archlinux.org/packages/?O=0&SeB=b&K=gpg-tui&outdated=&SB=n&SO=a&PP=50&do_Search=Go) and compile them with [makepkg](https://wiki.archlinux.org/index.php/Makepkg):

```sh
# clone the AUR repository
git clone https://aur.archlinux.org/gpg-tui-git.git && cd gpg-tui-git/

# build the package
makepkg -si
```

### Homebrew

To install the [Homebrew package](https://formulae.brew.sh/formula/gpg-tui), run:

```sh
brew install gpg-tui
```

To update, run:

```sh
brew upgrade gpg-tui
```

### Docker

#### Docker Hub

See available [tags](https://hub.docker.com/r/orhunp/gpg-tui/tags).

```sh
docker pull orhunp/gpg-tui:[tag]
```

You can also use the following alias for a quick launch:

```sh
alias gpg-tui='docker run -it -v "$HOME/.gnupg":/root/.gnupg orhunp/gpg-tui'
```

#### Using the Dockerfile

```sh
# clone the repository
git clone https://github.com/orhun/gpg-tui.git && cd gpg-tui/

# build the image
docker build -t gpg-tui .

# run the container
docker run -it gpg-tui
```

### FreeBSD

All required dependencies are automatically fetched and installed independently of the installation method chosen.

#### Building from source

```sh
# using a port
cd /usr/ports/security/gpg-tui
make install
```

```sh
# alternative method using portmaster
portmaster security/gpg-tui
```

#### Binary releases

```sh
# update repository catalogue (if outdated)
pkg update

# fetch and install the package
pkg install gpg-tui
```

### NetBSD

**gpg-tui** is available from the main [pkgsrc branch](https://pkgsrc.se/security/gpg-tui).

#### Install using the package manager

```sh
pkgin install gpg-tui
```

#### Building from source

```sh
cd /usr/pkgsrc/security/gpg-tui
make install
```

### Manually

#### Building from source

```sh
# clone the repository
git clone https://github.com/orhun/gpg-tui.git && cd gpg-tui/

# build and install
cargo install --root "$HOME/.cargo" --path .
```

#### Binary releases

See available [releases](https://github.com/orhun/gpg-tui/releases) that are automated by [Continuous Deployment](.github/workflows/cd.yml) workflow.

## Usage

```
gpg-tui [FLAGS] [OPTIONS]
```

```
FLAGS:
    -a, --armor      Enables ASCII armored output
        --splash     Shows the splash screen on startup
    -h, --help       Prints help information
    -V, --version    Prints version information
```

```
OPTIONS:
        --homedir <dir>        Sets the GnuPG home directory [env: HOMEDIR=]
    -o, --outdir <dir>         Sets the output directory [env: OUTDIR=]
    -d, --default-key <key>    Sets the default key to sign with [env: DEFAULT_KEY=]
    -t, --tick-rate <ms>       Sets the tick rate of the terminal [env: TICK_RATE=]  [default: 250]
    -c, --color <color>        Sets the accent color of the terminal [env: COLOR=]  [default: gray]
    -s, --style <style>        Sets the style of the terminal [env: STYLE=]  [default: plain]
                               [possible values: plain, colored]
```

## Key Bindings

### User Interface

| Key Binding          | Action                       |
| -------------------- | ---------------------------- |
| `?`                  | show help                    |
| `o,space,enter`      | show options                 |
| `hjkl,arrows,pgkeys` | navigate                     |
| `n`                  | switch to normal mode        |
| `v`                  | switch to visual mode        |
| `c`                  | switch to copy mode          |
| `p,C-v`              | paste from clipboard         |
| `a`                  | toggle armored output        |
| `1,2,3`              | set detail level             |
| `t,tab`              | toggle detail (all/selected) |
| `` ` ``              | toggle table margin          |
| `m`                  | toggle table size            |
| `C-s`                | toggle style                 |
| `/`                  | search                       |
| `:`                  | run command                  |
| `r,f5`               | refresh application          |
| `q,C-c/d,escape`     | quit application             |

### Key Management

| Key Binding   | Action        |
| ------------- | ------------- |
| `x`           | export key    |
| `s`           | sign key      |
| `e`           | edit key      |
| `i`           | import key(s) |
| `f`           | receive key   |
| `u`           | send key      |
| `g`           | generate key  |
| `d,backspace` | delete key    |
| `C-r`         | refresh keys  |

## Approach

Available keys in the keyring (which can be specified via `--homedir` argument) are showed on a table. This table consists of 2 columns which are [key information](#key-information) and [user information](#user-information).

The level of detail that an individual table row shows is determined by [detail levels](#detail-levels).

### Detail Levels

1. **Minimum**: shows only the primary key and user ID.

```
[sc--] rsa3072/B14085A20355B74DE0CE0FA1E19F76D037BD65B6  │  [u] Example Key <example@key>
```

2. **Standard**: shows all the subkeys and user IDs.

```
[sc--] rsa3072/B14085A20355B74DE0CE0FA1E19F76D037BD65B6  │  [u] Example Key <example@key>
|      └─(2021-05-14)                                    │   └─[u] Other User ID <example@key>
[--e-] rsa3072/E56CAC142AE5A979BEECB00FB4F68595CAD4E7E5  │
       └─(2021-05-14)
```

3. **Full**: shows signatures and notations.

```
[sc--] rsa3072/B14085A20355B74DE0CE0FA1E19F76D037BD65B6  │  [u] Example Key <example@key>
|      └─(2021-05-14)                                    │   │  └─[13] selfsig (2021-05-16)
[--e-] rsa3072/E56CAC142AE5A979BEECB00FB4F68595CAD4E7E5  │   │     └─[h] test@notation=xyz
       └─(2021-05-14)                                    |   └─[u] Other User ID <example@key>
                                                                   ├─[13] selfsig (2021-05-16)
                                                                   └─[10] 84C39331F6F85326 Other Signer Key <example@signer> (2021-05-16)
```

### Key Information

An example table entry for the detail level `full` (which includes subkeys) is explained via reference numbers below.

<pre>
[sc--]<b>⁰</b> rsa3072<b>¹</b>/B14085A20355B74DE0CE0FA1E19F76D037BD65B6<b>²</b>
|<b>³</b>      └─(2021-05-14)<b>⁴</b>
[--e-]<b>⁰</b> rsa3072<b>¹</b>/E56CAC142AE5A979BEECB00FB4F68595CAD4E7E5<b>²</b>
        └─(2021-05-14) -> (2021-05-16)<b>⁴</b> [exp]<b>⁵</b>
</pre>

**0**: Key flags. Determines what this key can do.

* `s`: sign
* `c`: certify
* `e`: encrypt
* `a`: authenticate

**1**: Algorithm of the key.

**2**: Fingerprint of the key.

**3**: Indicates that the next key is a subkey.

**4**: Time information of the key:

* creation time (`Y-m-d`)
* expiration time (`Y-m-d`)

**5**: Is the key one of the following?

* `[exp]`: expired
* `[rev]`: revoked
* `[d]`: disabled
* `[i]`: invalid
* `[q]`: qualified

### User Information

An example table entry for the detail level `full` (which includes other user IDs, signatures and notations) is explained via reference numbers below.

<pre>
[u]<b>⁰</b> Test Key &lt;test@test&gt;<b>¹</b>
 │<b>²</b>  └─[13]<b>³</b> selfsig<b>⁴</b> (2021-05-16)<b>⁶</b>
 │             └─[h]<b>⁹</b> test@notation=xyz<b>⁸</b>
 └─[u]<b>⁰</b> Test Key2 &lt;test2@test2&gt;<b>¹</b>
        ├─[13]<b>³</b> selfsig<b>⁴</b> (2021-05-16)<b>⁶</b>
        └─[10]<b>³</b> 84C39331F6F85326 Test Key 2 &lt;test2@example.com&gt;<b>⁵</b> (2021-05-16)<b>⁶</b> [!x]<b>⁷</b>
</pre>

**0**: Validity of the user.

* `q`: undefined
* `n`: never
* `m`: marginal
* `f`: full
* `u`: ultimate
* `?`: unknown

**1**: User ID. (`name` + `email`)

**2**: Indicates the next user ID.

**3**: Certification level of the signature.

* `10`: no indication
* `11`: personal belief but no verification
* `12`: casual verification
* `13`: extensive verification

**4**: Indicates that this is a self signature, whereby the users' own private key was used to sign their public key.

**5**: Key and user ID of the signer. (`key` + `name` + `email`)

**6**: Time information of the signature.

* creation time (`Y-m-d`)
* expiration time (`Y-m-d`)

**7**: Is the signature one of the following?

* `[exp]`: expired
* `[rev]`: revoked
* `[i]`: invalid
* `[!x]`: non-exportable

**8**: Notation data.

**9**: Flags associated with the notation data.

* `[h]`: the notation data is in human readable form
* `[!]`: the notation data is critical

## Features

Press `?` while running the terminal interface to see information about key bindings and GnuPG configuration.

![](demo/gpg-tui-help_menu.gif)

### User Interface

#### Scrolling

Use arrow or `hjkl` keys to scroll and navigate through lists/menus/tabs. Additionally, you can use `Ctrl-Up/Down` combinations or `PageUp`/`PageDown` keys to scroll to the top/bottom.

![](demo/gpg-tui-scrolling.gif)

If rows are not fitting on the terminal interface, use `Alt` + arrow/`hjkl` keys to individually scroll them.

![](demo/gpg-tui-scrolling_rows.gif)

![](demo/gpg-tui-scrolling_rows2.gif)

#### Options Menu

Most of the actions can be performed using the options menu. Simply press `Enter` and select what you want to do.

![](demo/gpg-tui-options_menu.gif)

#### Copy / Paste

There's a `copy` mode for making it easier to copy particular values to the clipboard. To use this mode, press `c` followed by one of the key bindings:

* `x`: Copy the exported key
* `i`: Copy the key id
* `f`: Copy the key fingerprint
* `u`: C