jkey
Cross-platform command-line password manager and TOTP verifier.
All data is encrypted with AES-256-CBC + HMAC-SHA256 and stored per data type under ~/.config/jkey/. Pure Python — no OpenSSL or libsodium required.
Install
pipx install jkey
Or with plain pip:
pip install --user jkey
Or run without installing:
pipx run jkey --help
Quick Start
# Initialize vault (set master password)
jkey pv init
# Add a 2FA account from QR code image
jkey 2fa add ./github.jpg
# List TOTP codes (optional keyword filter)
jkey 2fa ls
jkey 2fa ls github
# Generate a random password
jkey pm get -L 24
# Store a password
jkey pm add my-site
# List all stored passwords
jkey pm ls
# Encrypt/decrypt any file
jkey pv encrypt secret.pdf
jkey pv decrypt secret.pdf.jkey -o secret.pdf
Commands
| Command | Description |
|---|---|
jkey 2fa ls [keyword] |
List TOTP accounts and codes |
jkey 2fa add <image> |
Import from QR code image |
jkey 2fa rm <account> |
Remove a TOTP account |
jkey rc add <file> |
Import recovery codes from file |
jkey rc ls [keyword] |
List recovery codes |
jkey rc rm <account> |
Remove recovery codes |
jkey pm ls [keyword] |
List stored passwords |
jkey pm get [-L N] |
Generate a random password |
jkey pm add <name> |
Store a password (prompts for input) |
jkey pm edit <name> |
Update an existing password |
jkey pm rm <name> |
Delete a stored password |
jkey pm import <file.csv> |
Import passwords from a browser CSV export |
jkey pv init |
Initialize the encrypted vault |
jkey pv unlock |
Unlock the vault |
jkey pv lock |
Lock the vault |
jkey pv status |
Show vault status |
jkey pv set-pw |
Change master password |
jkey pv encrypt <file> |
Encrypt a file |
jkey pv decrypt <file> |
Decrypt a .jkey file |
jkey pv export totp |
Export TOTP secrets (re-enters master password) |
jkey pv export passwords |
Export passwords as CSV |
jkey pv export recovery |
Export recovery codes |
jkey pv export qr -o <dir> |
Export QR code images |
jkey pv export all -o <dir> |
Export everything |
jkey remote add <name> <url> |
Configure a local, S3, or rclone backend |
jkey remote ls |
List configured backends |
jkey remote rm <name> |
Remove a backend configuration |
jkey backup <name> |
Upload the encrypted vault |
jkey restore <name> |
Restore the latest backup; keep local conflicts as .bak |
Set JKEY_PASS environment variable to skip the password prompt. Set JKEY_SESSION_TIMEOUT to change the session cache lifetime (default: 300 seconds).
Sessions use per-terminal tickets: unlocking in one terminal window does not unlock other windows. The master password is cached only in a native OS credential store (Linux Secret Service, macOS Keychain, or Windows Credential Manager). Disk tickets contain only expiry and vault fingerprint metadata; decrypted records are never cached on disk. Old plaintext tickets are removed on first use. If no supported, unlocked credential store is available, commands work normally but each new command requires authentication. jkey pv lock invalidates every terminal's ticket and removes its cached credential.
Backup & Restore
Configure a backend once, then upload and restore with one command each:
jkey remote add s3 s3://my-bucket/jkey
jkey backup s3
jkey restore s3
The name is your choice. Local directories, NAS mounts and USB drives work too:
jkey remote add nas /mnt/nas/jkey
jkey backup nas
jkey restore nas
Or reuse an existing rclone remote directly, with no jkey configuration:
jkey backup rclone:r2
jkey restore rclone:r2
Both commands transfer encrypted data and need no master password. Restore asks for confirmation. Identical files are skipped; differing local files are kept as filename.jkey.bak before replacement. Existing .bak files are preserved with timestamped names for subsequent conflicts. Files present only locally are left alone. Nothing is merged automatically.
Use jkey restore s3 -o ./restored to restore to a different directory. See backend configuration and conflict handling for details.
How It Works
Data is encrypted with AES-256-CBC + HMAC-SHA256 and stored in ~/.config/jkey/:
~/.config/jkey/
├── sessions/ # Per-terminal session tickets (sudo-style, 5 min activity timeout)
├── remotes.json # Backup remote configs (mode 600; never contains vault data)
├── totp.jkey # Encrypted TOTP secrets
├── passwords.jkey # Encrypted passwords
├── recovery.jkey # Encrypted recovery codes
└── qr/ # Encrypted QR images
For machine migration use jkey backup <remote> + jkey restore <remote>, or manually back up ~/.config/jkey/ (excluding sessions/).
Dependencies
Runtime dependencies:
portalocker— cross-platform vault file lockingkeyring— native OS credential storage for session passwords (no file-based fallback)opencv-python-headless— optional, needed only forjkey 2fa addQR scanning. Install withpip install jkey[qr].boto3— optional, needed only for natives3://backends. Install withpip install jkey[s3].rcloneexecutable — optional, needed only forrclone:backends. Uses your existing rclone configuration.
Pure Python, no OpenSSL or libsodium required.
Metadata
Release files for jkey 0.5.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jkey-0.5.2.tar.gz | 65.0 kB | With provenance | Details for jkey-0.5.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jkey-0.5.2-py3-none-any.whl | Python 3 | none | any | Details for jkey-0.5.2-py3-none-any.whl |
Total release size: 113.4 kB
Release files / jkey-0.5.2.tar.gz
| Download URL | jkey-0.5.2.tar.gz |
|---|---|
| Size | 65.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4505f72549160ffc578de1bd8c58a3b50e6fb0c7f997479098e8a3a1a0edac1b
|
|
BLAKE2b-256 checksum How to use checksums |
222b95292e07fdc5ca67a458cafcadfb3ceef254fc5c2f56106ee076e503ae43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / jkey-0.5.2-py3-none-any.whl
| Download URL | jkey-0.5.2-py3-none-any.whl |
|---|---|
| Size | 48.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67ebd733395ddef8a4bb894e9783564c92a8f743d488f523daf0d0fd5e333cc7
|
|
BLAKE2b-256 checksum How to use checksums |
0eaf705ef1583dd3fe5b8dc4f7c6b9b6269b143e2ffee42b43de3b59dfcbe7a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for jkey 0.5.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for jkey-0.5.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.