Use oathtool Linux command line for 2 step verification (2FA)

last updated in Categories , , , , ,

I do not wish to use Google Authenticator or Authy app that generates 2 step verification (2FA) codes on my iOS/Android phone. Is there any way I can produce 2FA codes from Linux command line for popular sites such as Gmail, Twitter, Facebook, Amazon and more?

The mobile apps generate secure 2 step verification codes to protect your online accounts from hackers. You get an additional layer of security. In addition to your password, you need to input 2FA codes for each login. This page explains how to use oathtool OTPs (one-time password) on Linux to secure your Gmail and other online accounts. Instead of waiting for text messages, get verification codes for free from the oathtool Linux command.


How to install oathtool Linux command line tool

oathtool is a command line tool for generating and validating OTPs and gpg2 is an OpenPGP encryption and signing tool for encrypting private keys used by oathtool. Type the commands as per your Linux distro to install the same.

Fedora Linux install oathtool

Open the terminal application and type the following dnf command:
$ sudo dnf install oathtool gnupg2

CentOS Linux/RHEL install oathtool

First enable EPEL repo on RHEL or CentOS 7 and run the following yum command:
$ sudo yum install oathtool gnupg2

Debian/Ubuntu Linux install oathtool

Simply use the apt command or apt-get command to install the same:
$ sudo apt update
$ sudo apt upgrade
$ sudo apt install oathtool gnupg2

SUSE/OpenSUSE Linux install oathtool

Simply run the following [nixcmd name=”zypper”:
$ sudo zypper ref
$ sudo zypper in oath-toolkit gpg2

Linux 2 step verification (2FA) using oathtool

The syntax to generate totp is as follows:
oathtool -b --totp 'private_key'
Typically private_key only displayed once when you enable 2FA with online services such as Google/Gmail, Twitter, Facebook, Amazon, PayPal, Bank accounts and so on. You must keep private_key secrete and never share with anyone. Here is a sample session that creates code for my Twitter account.
$ oathtool -b --totp 'N3V3R G0nn4 G1v3 Y0u Up'
Sample outputs:


How to generate Two-Factor authentication code from your Linux CLI

Generate a new key pair for encryption if you don’t have a gpg key, run:
$ gpg2 --full-gen-key
Generate two-factor authentication code from your Linux CLI
Next, create some directories and helper scripts:
$ mkdir ~/.2fa/
$ cd ~/.2fa/

You can list GPG keys including GnuPG user id and key id, run:
$ gpg --list-secret-keys --keyid-format LONG

Shell script helper script to encrypt the totp secret (keys)

Create a shell script named

# Purpose: Encrypt the totp secret stored in $dir/$service/.key file
# Author: Vivek Gite {} under GPL v 2.x or above
# --------------------------------------------------------------------------
# Path to gpg2 binary
## run: gpg --list-secret-keys --keyid-format LONG to get uid and kid ##
# GnuPG user id 
# GnuPG key id 
# Directory that stores encrypted key for each service 
# Now build CLI args
# failsafe stuff
[ "$1" == "" ] && { echo "Usage: $0 service"; exit 1; }
[ ! -f "$k" ] && { echo "$0 - Error: $k file not found."; exit 2; }
[ -f "$kg" ] && { echo "$0 - Error: Encrypted file \"$kg\" exists."; exit 3; }
# Encrypt your service .key file 
$_gpg2 -u "${kid}" -r "${uid}" --encrypt "$k" && rm -i "$k"

Shell script helper script to decrypt the totp secret and generate 2FA code

Create a shell script named

# Purpose: Display 2FA code on screen
# Author: Vivek Gite {} under GPL v 2.x or above
# --------------------------------------------------------------------------
# Path to gpg2 binary
## run: gpg --list-secret-keys --keyid-format LONG to get uid and kid ##
# GnuPG user id 
# GnuPG key id 
# Directory 
# Build CLI arg
# failsafe stuff
[ "$1" == "" ] && { echo "Usage: $0 service"; exit 1; }
[ ! -f "$kg" ] && { echo "Error: Encrypted file \"$kg\" not found."; exit 2; }
# Get totp secret for given service
totp=$($_gpg2 --quiet -u "${kid}" -r "${uid}" --decrypt "$kg")
# Generate 2FA totp code and display on screen
echo "Your code for $s is ..."
code=$($_oathtool -b --totp "$totp")
## Copy to clipboard too ##
## if xclip command found  on Linux system ##
type -a xclip &>/dev/null
[ $? -eq 0 ] && { echo $code | xclip -sel clip; echo "*** Code copied to clipboard too ***"; }
echo "$code"
# Make sure we don't have .key file in plain text format ever #
[ -f "$k" ] && echo "Warning - Plain text key file \"$k\" found."

2FA using oathtool in the Linux command line for Gmail account

Let us see a complete example for Google/Gmail account. To enable 2FA visit and login:
Visit 2-Step Verification > Get Started:
Gmail 2-Step Verification
You may have to verify your mobile phone number. Once verified, scroll down and choose Authenticator app:
Set up Authenticator app
What kind of phone do you have? Choose iPhone or Android as we are going to use our CLI app and click Next:
Get codes from the Linux authenticator cli app
Make sure you click on “CAN’T SCAN IT” to see totp secret key and copy it:
Can't scan the barcode for Linux 2FA app
Cd into ~/.2fa/ directory and run the following commands:
cd ~/.2fa/
### Step 1. create service directory ###
### also act as service name for ###
### Step 2. Store totp secret key ###
echo -n 'hilp zs6i c5qu bx7z akiz q75e wk5z z66b' > ~/.2fa/

Encrypt the totp secret key file named ~/.2fa/ with gpg and password protect it for security and privacy reasons using our helper script:
### Step 3. Secure totp secret key for service named ###

Linux 2 step verification 2FA totp key file
Finally click on the Next button:
Set up Linux oathtool as authenticator app
It is time to create your first 6-digit code using oathtool command. However, we automated this process using shell script that decrypts the totp secret and generates the 6-digit 2FA code. Simply run:
You need to type the gpg passphrase to unlock the secrete key for service named
oathtool Linux command line with shell script helper
Finally you will see the 6-digit code as follows on screen:
Generate Two-Factor Authentication Codes on Linux
Withing 30 seconds you need to type the 330197 code and click on the verify button:
Enter 6 digit code for Gmail from Linux command line
And you are done:
totp linux set up

How to add another service

The syntax is pretty simple:

  1. Log in to online service such as Twitter, Facebook, Bank account and look for Authenticator 2FA app. For example, let us set up Twitter account 2FA using Linux command line app.
  2. Copy the totp secret from Twitter account.
  3. Create a new service directory: mkdir ~/.2fa/
  4. Make a new .key file: echo -n 'your-twitter-totp-secret-key' > ~/.2fa/
  5. Generate a new PGP encrypted file for security and privacy reasons: ~/.2fa/
  6. Decrypts the totp secret and generates the 6-digit 2FA code when you need to log in into Twitter: ~/.2fa/

You can repeat the above process for any services that display the totp secret along with QR code.


The main advantage of Linux command line is that you can easily backup your ~/.2fa/ directory and keys. Your totp secrets/keys are always encrypted and password protected by gpg2. Mobile apps such as Google Authenticator usually do not allow you to sync or copy secrets/keys for security reasons. So if you lost phone or switch phone, you wouldn’t be able to login into the account. This set up is simple and easy to backup/restore as long as you remember your gpg2 passphrase. I strongly recommend that you enable full disk encryption (FDE) too. Next time I will show you how to use GUI apps for the same purpose. See oathtool man page for more information here.


Posted by: Vivek Gite

The author is the creator of nixCraft and a seasoned sysadmin, DevOps engineer, and a trainer for the Linux operating system/Unix shell scripting. Get the latest tutorials on SysAdmin, Linux/Unix and open source topics via RSS/XML feed or weekly email newsletter.

Notable Replies

  1. Are you using correct gpg key? Did you set up gpg key? Also don’t run command as root. This should be run as normal user.

  2. yes as long as all account have same keys.

  3. Hallo!

    This was a great tutorial on the topic of using TOTP on GNU/Linux PCs, probably the best I came along in the internet. Thank you indeed for that! Now, I have a special case:

    For specific reasons my computer time is intentionally 19 to 20 minutes ahead of the actual time. This of course renders a problem for the creation of TOTPs. Fortunately, oathtool offers the possibilty to manually define the current time with the --now argument. It expects an option like ‘2019-12-23 19:01:21 UTC’. As a work-around I manually change this in the script, but it would of course be nice it this could be done automatically.

    Now, by use of sntp programm you can display your computer time and the offset from UTC. It returns a result like

    $ sntp
    sntp 4.2.8p12@1.3728-o (1)
    Can't open KOD db file /var/lib/sntp/kod for writing: Permission denied
    2019-12-23 23:55:39.167286 (-0100) -1169.921316 +/- 779.947834 s1 no-leap

    So in this case you would determine UTC by substracting one hour (-0100) and approximately 1170 seconds (-1169,921…). I am sure it would not be to hard to implement this in the code, but I am not skilled enough. Would anyone have an idea how to code this?

    Best regards

  4. @theltalpha

    Use the following to get date in utc format and that too 20 mins ago:

    date --utc -d '20 min ago'

    For the --now argument try:

    date --utc -d '20 min ago' +"%Y-%m-%d %T UTC"

    For example, at the CLI:

    NOW=$(date --utc -d '20 min ago' +"%Y-%m-%d %T UTC")
    oathtool -b --totp "$totp" --now "$NOW"

    One can modify script as follows

    NOW=$(date --utc -d '20 min ago' +"%Y-%m-%d %T UTC")
    code=$($_oathtool -b --totp "$totp" --now "${NOW}")


Continue the discussion

7 more replies


Historical Comment Archive

12 comment

    Still, have a question? Get help on our forum!