freeotp-vault

Encrypted CLI vault for FreeOTP JSON exports with system keyring support.

Install

pip install freeotp-vault

For system keyring support (to store password securely):

pip install freeotp-vault[keyring]
# or on Debian/Ubuntu:
sudo apt install libsecret-1-0 libsecret-tools

Usage

Import a FreeOTP backup

freeotp-vault init path/to/freeotp-export.json

List accounts

freeotp-vault list
freeotp-vault list --filter github

Generate tokens

freeotp-vault token
freeotp-vault token --filter github

Change password

freeotp-vault change-password

Remove accounts

freeotp-vault remove --filter "old account"

Automatic Backups

Every time the vault is saved, a timestamped backup is created in ~/.config/freeotp-vault/backups/. Up to 5 backups are retained.

Google Drive Sync

Backup and sync your vault with Google Drive for cross-device access.

Setup:

1. Create OAuth credentials:

   • Go to Google Cloud Console
   • Create OAuth client ID → Desktop app
   • Download as credentials.json
   • Save to ~/.config/freeotp-vault/credentials.json

2. Authenticate:

freeotp-vault gdrive-login

Sync commands:

# Upload vault to Google Drive
freeotp-vault gdrive-sync --upload

# Download vault from Google Drive
freeotp-vault gdrive-sync --download

Python API

from freeotp_vault import (
    encrypt_vault,
    decrypt_vault,
    parse_freeotp_json,
    generate_token,
    get_password_from_keyring,
    store_password_in_keyring,
)

# Parse a FreeOTP JSON export
tokens = parse_freeotp_json(json_string)

# Encrypt/decrypt vault data
blob = encrypt_vault(data, "password")
plaintext = decrypt_vault(blob, "password")

# Generate OTP code
code = generate_token(token_dict)

Development

git clone https://github.com/daedalus/freeotp-vault.git
cd freeotp-vault
pip install -e ".[test]"

# With Google Drive support
pip install -e ".[gdrive]"

License

MIT License - see LICENSE file.