totp-devkey

Developer CLI for TOTP (2FA) authentication. Save secrets by name, get live codes, scan QR screenshots — all from the terminal.

totp github JBSWY3DPEHPK3PXP    # save key
totp github                       # get current code

No phone needed during development.

Install

npm install -g totp-devkey

Or run without installing:

npx totp-devkey github

Usage

Save a key

totp <name> <base32-secret>

totp github JBSWY3DPEHPK3PXP
totp aws.dev KRUGKICCMFAUCNKPJVKEKNCLJNBUWI3L

Running the same command again updates the key.

Get current code

totp <name>

totp github
#  github
#  696 256   ████████░░  22s

The code is formatted XXX XXX for easy reading. The bar shows time remaining (turns red under 5s).

Live countdown

totp github --watch
# 696 256  ████████░░  22s   (updates every second, Ctrl+C to exit)

Import from clipboard

Copy an otpauth:// URI or raw secret, then:

totp github --paste

Works with anything copied from a QR code scanner app, Bitwarden export, or an otpauth://totp/... URI.

Scan a QR code screenshot

# From a file
totp github --scan ~/Downloads/github-2fa-qr.png

# From clipboard image (macOS — copy screenshot with Cmd+Ctrl+Shift+4)
totp github --scan clip

Supports PNG, JPEG, and most common image formats. Automatically parses the otpauth:// URI from the QR code and saves all metadata (issuer, digits, period, algorithm).

Import from otpauth:// URI

totp github --uri "otpauth://totp/GitHub%3Adev%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub"

List all accounts

totp --list

#  3 accounts  (~/.config/totp-devkey/keys.json)
#
#  github
#  696 256   ████████░░  22s
#
#  aws.dev  · AWS
#  123 456   █████░░░░░  15s
#
#  gitlab
#  789 012   ██░░░░░░░░  6s

Delete an account

totp --delete github

All commands

| Command | Description | |---|---| | totp <name> <secret> | Save or update a base32 secret | | totp <name> | Show current TOTP code | | totp <name> --watch | Live countdown (updates every second) | | totp <name> --paste | Import from clipboard text | | totp <name> --scan <file> | Scan QR code from image file | | totp <name> --scan clip | Scan QR from clipboard image (macOS) | | totp <name> --uri <uri> | Import from otpauth:// URI | | totp --list | List all accounts with live codes | | totp --delete <name> | Remove an account | | totp --help | Show help |

Storage

Keys are saved to ~/.config/totp-devkey/keys.json with permissions 600 (owner read/write only). The directory is 700.

{
  "github": {
    "secret": "JBSWY3DPEHPK3PXP",
    "issuer": "GitHub",
    "algorithm": "SHA-1",
    "digits": 6,
    "period": 30,
    "updatedAt": "2026-06-04T09:00:00.000Z"
  }
}

No encryption at rest — treat this file like an SSH key. If you need encrypted storage, consider using the system keychain.

QR scanning

QR scan uses jimp + jsqr — pure JS, no native binaries. Works on macOS, Linux, and Windows.

For clipboard image scanning on macOS, a temporary file is written to /tmp, scanned, then deleted immediately.

Requirements

• Node.js 18+
• macOS, Linux, or Windows

License

MIT