https://github.com/kernc/totp
🔢 TOTP on-terminal PIN (token generator)
https://github.com/kernc/totp
Last synced: 5 days ago
JSON representation
🔢 TOTP on-terminal PIN (token generator)
- Host: GitHub
- URL: https://github.com/kernc/totp
- Owner: kernc
- License: agpl-3.0
- Created: 2026-07-19T23:41:31.000Z (5 days ago)
- Default Branch: master
- Last Pushed: 2026-07-20T00:11:45.000Z (5 days ago)
- Last Synced: 2026-07-20T01:26:06.308Z (5 days ago)
- Language: Shell
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
TOTP On-Terminal PIN (generator)
================================
[](https://github.com/kernc/totp/actions)
[](https://github.com/kernc/totp/actions)
[](https://github.com/kernc/totp)
[](https://ghloc.vercel.app/kernc/totp)
[](https://github.com/kernc/totp)
[](https://github.com/kernc/totp)
[](https://github.com/sponsors/kernc)
[](https://github.com/kernc/totp/issues)
Manage "authenticator" time-based OTP tokens most simply in your beloved terminal.
Written in somewhat dense POSIX Shell.
On disk, the secrets are encrypted with a password using OpenSSL AES256 CTR.
This project vendors the excellently concise [`totp` computer by **@KevCui**](https://github.com/KevCui/totp/blob/master/totp).
Installation
------------
```sh
# Discover dependencies already installed
sudo apt install openssl
# Download the latest release and unpack into $HOME/.totp
mkdir -p "$HOME/.totp"
curl -L 'https://github.com/kernc/totp/archive/master.tar.gz' |
tar -C "$HOME/.totp" -xvz --strip-components 1 --exclude .github
```
Usage
-----
All of the contained are very simple scripts that (may) read lines on stdin
and take no command line arguments.
Import some QR codes using either `otpauth://` or
`otpauth-migration://` URI scheme:
```script
$ sudo apt install zbar-tools
$ zbarimg path/to/qr1.png
QR-Code:otpauth://totp/Login?secret=GEZDGNBVGY3TQOIK&issuer=Employer
$ zbarimg path/to/qr*.png | grep -o otpauth.* > otpauth_uris.list
$ .totp/import < otpauth_uris.list
Enter PASSWORD:
```
You pick a password for the encryption of secrets on disk.
If the password is blank, the secrets will be left plaintext (unsafe).
You can have different passwords for different secrets;
simply invoke `import` multiple times.
Assuming your system time is correct, get the latest PIN tokens:
```script
$ .totp/totp
123456 Employer/Login
331666 Google/auth
012489 CoinWallet/x
totp: Password unlocks 3/5 secrets
totp: New codes in 14 seconds
```
As you can see again, you can have different passwords for different secrets.
If need arises, export to QR codes or plaintext URIs:
```script
$ .totp/export
totp_qr1.png otpauth://...
totp_qr2.png otpauth://...
totp_qr3.png otpauth://...
```
See the [test suite](https://github.com/kernc/totp/blob/master/lib/test.sh)
for more usage examples!
Environment variables
---------------------
* **`PASSWORD=`** Preset the password to encrypt/decrypt the secrets
so that the program can run without asking.
If the password is empty, the secrets are left unencrypted.
* **`SECURITY_TOKEN=`** If set, the password will be derived from a PKCS#11
**hardware security token** _object URL_
[matching this string](https://github.com/search?q=repo%3Akernc%2Ftotp+%24SECURITY_TOKEN&type=code).
List available token object URL strings with:
```shell
p11tool --list-token-urls | grep 'type=private'
```
Runtime dependencies to use the feature:
```shell
sudo apt install libengine-pkcs11-openssl
```
* **`SECRETS_DIR=`** Save/read secrets from this directory (default: `$HOME/.totp/secrets`).
* **`VERBOSE=`** Make `totp` emit _three_ instead of two Tab-separated columns: PIN, label, and the full export URI.