Discover, install, and configure shell plugins with Fig Plugin Store →

Oath (alexdesousa)

Zsh plugin to manage one-time passwords.

8 stars
0 forks


A solemn pledge or promise, appealing to a deity, a ruler, or another entity (not necessarily present) to attest to the truth of a statement or sincerity of one's desire to fulfill a contract or promise.

Oath is an Oh My ZSH plugin that manages 2FA authentication 6 digit tokens. It's highly inspired in this article.


Oath pre-requisites are as follows:

  • oathtool for generating 6 digit tokens.
  • gnupg2 for handling private keys securely.
  • xclip for copying to clipboard.
  • An RSA 4096 bits long key (check this section for generating a key).

Small Example

Oath allows to add, remove keys as well as show the temporal 6 digit token e.g:

  • Adding a new key for a domain e.g. for
  ~ $ oath add
  Private Key:
  [SUCESS]  Key created for
  • Deleting a key for a domain e.g. for
  ~ $ oath delete
  [WARN]    Deleting $OATH_DIR/.oath/
  [WARN]    Deleting $OATH_DIR/.oath/
  [SUCCESS]  Key deleted for
  • Showing (and copying to clipboard) the current 6 digit token e.g. for
  ~ $ oath
  [SUCCESS]  Code copied to clipboard
  • Showing (and copying to clipboard) the key for a domain e.g. for
  ~ $ oath pk
  [SUCCESS]  Private key copied to clipboard
  • Listing keys for all domains e.g:
  ~ $ oath list
  • Updating Oath to latest version:
  ~ $ oath update


Just clone Oath as follows:

~ $ git clone "" "$ZSH_CUSTOM/plugins/oath"

And add the oath to your plugins in $HOME/.zshrc file:

# Activate completions
autoload -U +X compinit && compinit
autoload -U +X bashcompinit && bashcompinit


# Variables for Oath
export OATH_KEY=<My Oath key>
export OATH_EMAIL=<My Oath email>

Important: when updating you can run the following:

cd `$ZSH_CUSTOM/plugins/oath` && git pull origin master

Generating a Key

First you need to create a key with gpg2 as follows:

$ gpg2 --full-gen-key

This will prompt several questions:

  1. Kind of key: Hit [Enter] or choose 1 for RSA and RSA:

    gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
    Please select what kind of key you want:
        (1) RSA and RSA (default)
        (2) DSA and Elgamal
        (3) DSA (sign only)
        (4) RSA (sign only)
      (14) Existing key from card
    Your selection? 1
  2. Key size: 4096 is recommended.

    RSA keys may be between 1024 and 4096 bits long.
    What keysize do you want? (3072) 4096
    Requested keysize is 4096 bits
  3. Expiration: Choose 0 for no expiration.

    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) 0
    Key does not expire at all
  4. Hit y if everything is correct.

    Is this correct? (y/N) y
  5. Identify the key with:

    GnuPG needs to construct a user ID to identify your key.
    Real name: Alex de Sousa
    Email address:
    Comment: My Oath key
    You selected this USER-ID:
        "Alex de Sousa (My Oath key) <>"
  6. Hit o if everything is correct.

    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
  7. Move you mouse to generate entropy:

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
  1. Retrieve your key:

    gpg: key 6759ADDD12CB6379 marked as ultimately trusted
    gpg: revocation certificate stored as '/home/alex/.gnupg/openpgp-revocs.d/424184E122529120CC1821756759ADDD12CB6379.rev'
    public and secret key created and signed.
    pub   rsa4096 2020-02-06 [SC]
    uid                      Alex de Sousa (Oath key) <>
    sub   rsa4096 2020-02-06 [E]

Then we'll only need the email and the key uid e.g. in our example the the following two values:

  • OATH_KEY: 424184E122529120CC1821756759ADDD12CB6379

Important: The key will be in your $HOME/.gnupg folder. Saving this folder is enough to back it up.


Alexander de Sousa.


Oath is released under the MIT License. See the LICENSE file for further details.