cotp

cotp - command line TOTP/HOTP authenticator

I believe that security is of paramount importance, especially in this digital world. I created cotp because I needed a minimalist, secure, desktop accessible software to manage my two-factor authentication codes.

Overview

Interface

Run cotp to open your vault. The dashboard adapts to your terminal, with searchable accounts, a countdown for the selected code, grouped codes, and an account detail panel on wide screens. On your first run, choose a password to initialize the encrypted database.

Use the keyboard for every action, or click accounts, the search bar, and the visible shortcuts. Keyboard and mouse-wheel navigation stop at the first and last account. The ? menu also offers clickable actions. No special icon font is required. The dashboard needs an interactive terminal; use cotp list or cotp list --json when piping output.

Key	Action
↑ / ↓, k / j	Select an account
Home / End, PgUp / PgDn	First / last account, or move ten accounts
/ or Ctrl+F	Filter by issuer or account label
Enter	Copy the selected code; on the QR screen, copy its OTP URI
a / e	Add / edit an account
Space	Show or close the selected account's QR code
h	Hide / reveal codes
+ / -	Increase / decrease an HOTP counter
d or Delete	Delete an account, with confirmation
? or i	Open the shortcuts and actions menu
Esc	Close the current screen, finish searching, clear a filter, or quit
q, Ctrl+C, Ctrl+D	Quit; account changes prompt you to save or discard

Add and edit accounts

Press a or click Add to enter an issuer, account label, and secret. You can also paste an otpauth:// URI into the secret field to populate the form. Choose the OTP type and algorithm, then adjust digits, period, counter, or PIN as required. Validation focuses the field that needs attention.

Use Tab / Shift+Tab or ↑ / ↓ to move through fields and buttons. Text fields support cursor movement, Home, End, and Ctrl+U to clear. Click a type or algorithm field, or use ← / → or Space, to change it. Ctrl+S or Save account applies the form; Esc or Cancel discards it. Secret keys and PINs are masked; when editing, leave either blank to keep its existing value.

Account additions, edits, deletions, and counter changes remain pending until you quit and confirm save. Choosing discard leaves the on-disk vault unchanged. CLI subcommands remain available for scripting; run cotp --help for examples.

TL;DR

# Display all the OTP codes in the interactive dashboard
cotp # select any code with arrow keys, press enter to copy into the clipboard, even in an SSH remote shell

# In the dashboard, press a to add or e to edit an account

# Add a new TOTP code from a BASE32 secret key
cotp add --label [email protected] --issuer Google

# Add a new HOTP code with custom algorithm, digits and counter
cotp add --label example --type hotp --algorithm SHA256 --digits 8 --counter 10

# Edit the digits of the 4th OTP code
cotp edit --index 4 --digits 8

# List all the codes in JSON format passing password through stdin
echo "mysecretpassword" | cotp --password-stdin list --json

# Extract the first matching OTP code with "google" issuer and copy it into the clipboard
cotp extract --issuer google --copy-clipboard

# Import an encrypted Aegis Database backup
cotp import --path my_db.json --aegis-encrypted

# Export the cotp database
cotp export

Compatibility

cotp can generate both TOTP and HOTP codes, compliant with rfc6238 and rfc4226 specifications. Also, it is possible to customize settings like HMAC algorithm and digits, to provide compatibility to other two-factor authentication systems.

Latest releases also include support for Steam, Yandex, MOTP codes.

Encryption

This program relies on only one database file encrypted with XChaCha20Poly1305 authenticated encryption and Argon2id for key derivation.

It also uses AES-GCM to import from encrypted Aegis backups.

Cross Platform

cotp should be easily compiled on the most used platforms, but it is mostly tested on Linux, Windows and macOS.

Install

Arch Linux / Manjaro / Debian / Ubuntu / NixOS / others...

cotp is distributed in some of the mayor Linux distro repositories. Please check the repology badge at the top to know if your distribution already provides a package. I will try to push to more repositories over time.

Otherwise you have other options as explained in the next paragraph.

Other linux distributions and *nix

Before beginning check that you have the required build dependencies to use the rust compiler.

You need to install the libxcb-devel dependency, needed for clipboard coping in X11:

• Debian based: sudo apt install libxcb1-dev libx11-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev xclip
• Fedora / RHEL based: sudo dnf install libX11-devel
• Void Linux sudo xbps-install -S libxcb-devel

macOS

brew install cotp

Windows

Building is supported with both x86_64-pc-windows-gnu and x86_64-pc-windows-msvc toolchains.

If you want to use x86_64-pc-windows-msvc you will need to install the Visual C++ 2019 Build Tools

Once you have the rust toolchain installed just run cargo install cotp.

Use the crates.io repository

Just type cargo install cotp and wait for the installation.

Clone the GitHub repository and manually install

You can build cotp using these commands:

git clone https://github.com/replydev/cotp.git
cargo install --path cotp/

Migration from other apps

cotp supports TOTP codes migration from various apps. Some needs to be converted using simple python script you can find listed in the table below.

App	How to fetch backup	Needs conversion	cotp argument
andOTP	Make a backup using the app itself.	No	--andotp
Aegis	Make a backup using the app itself.	No	--aegis
Aegis (encrypted)	Make an encrypted backup using the app itself.	No	--aegis-encrypted
Authy	Obtain /data/data/com.authy.authy/shared_prefs/com.authy.storage.tokens.authenticator.xml from your phone.	Yes	--authy
Authy (2nd method)	Follow this guide: https://gist.github.com/gboudreau/94bb0c11a6209c82418d01a59d958c93.	No	--authy-exported
cotp	Export your database using cotp export.	No	--cotp
FreeOTP	Obtain /data/data/org.fedorahosted.freeotp/shared_prefs/tokens.xml from your phone.	Yes	--freeotp
FreeOTP+	Make a backup using the app itself.	No	--freeotp-plus
Google Authenticator	In the app open the menu, choose "Transfer accounts" > "Export accounts", select the accounts and let it generate the QR code(s). Scan each QR code with any scanner and save the resulting otpauth-migration://... URI(s), one per line, into a text file.	No	--google-authenticator
Microsoft Authenticator	Obtain /data/data/com.azure.authenticator/databases/PhoneFactor from your phone. Take also PhoneFactor-wal, PhoneFactor-shm if they exist in the same folder.	Yes	--microsoft-authenticator
OTP URI list	Create a JSON file which contains a items property. It will contains a string array where each element is an OTP URI.	No	--otp-uri

How to convert

Once you got the correct files run the right python script located in the converters/ folder in this source code.

Example: python authy.py path/to/database.xml converted.json

It will convert the database in a json format readable by cotp.

To terminate the import: cotp import --authy --path path/to/converted_database.json

Configuration

By default database is located in $HOME/.cotp/db.cotp. If you want to use a different path, you can use COTP_DB_PATH environment variable or use the --database-path argument. The first can be configured in shell configuration files, the second in package managers where the configuration of environment variables is not allowed, like Scoop.

These are examples of how to do this in bash:

$ COTP_DB_PATH=/home/user/.local/custom-folder/db.cotp cotp

or

$ cotp --database-path /home/user/.local/custom-folder/db.cotp

Planned features

Currently, there is not any planned feature. If you need something new that could improve the software feel free to open an issue.

Contribution

I created this project for my own needs, but I would be happy if this little program is useful to someone else, and I gratefully accept any pull requests.

UI development

The repository pins Rust and Cargo in rust-toolchain.toml; rustup installs the selected toolchain automatically. The interface uses Ratatui, Crossterm, and tui-input. Rendering and interaction tests cover responsive layouts, keyboard and mouse actions, forms, search, code timing, and masked fields.

To regenerate the documentation previews from the real widgets and demonstration data:

COTP_UI_PREVIEW=img/cotp-dashboard.svg COTP_FORM_PREVIEW=img/cotp-editor.svg cargo test interface::tests

To rebuild the animated demo with deterministic example accounts, install ImageMagick (magick) and run:

python3 ci/render_ui_demo.py

The recording uses the actual dashboard widgets and keyboard/mouse handlers, with synthetic accounts and masked secrets. Tutorial captions appear below the application.