Skip to main content

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 locking
  • keyring — native OS credential storage for session passwords (no file-based fallback)
  • opencv-python-headless — optional, needed only for jkey 2fa add QR scanning. Install with pip install jkey[qr].
  • boto3 — optional, needed only for native s3:// backends. Install with pip install jkey[s3].
  • rclone executable — optional, needed only for rclone: 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)

Source distribution for jkey 0.5.2
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)

Table of built distributions (wheels) for jkey 0.5.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page