OTPCLIENT-CLI(1)

📦
version 5.1.5 · 3 versions
, in nixpkgs unstable, ubuntu stonking

💖 OTPCLIENT-CLI(1) 💖

okay bestie, welcome to the OTPClient Manual — this is the page for otpclient-cli, the command-line bestie of the OTPClient GUI. she's lowkey iconic and she's about to carry your whole two-factor life. 🎀

✨ NAME ✨

otpclient-cli — the command-line interface for OTPClient. no windows, no buttons, just vibes and OTPs. 💅

🌸 SYNOPSIS 🌸

so here's the mood board, fr fr:

otpclient-cli --show [-d DB] [-a ACCOUNT] [-i ISSUER] [-m] [-n]
[--output FORMAT]
otpclient-cli --list [-d DB] [--output FORMAT]
otpclient-cli --list-databases [--output FORMAT]
otpclient-cli --list-types
otpclient-cli --import --type TYPE --file PATH [-d DB]
otpclient-cli --export --type TYPE [--output-dir DIR] [-d DB]
otpclient-cli --export-settings [--file PATH]
otpclient-cli --import-settings --file PATH

🦋 DESCRIPTION 🦋

otpclient-cli is the command-line counterpart to the OTPClient GUI. like, they're literally the same girl, different outfit. 💖

she can:

  • show one-time passwords
  • list the contents of a database
  • import or export tokens in any of the supported formats
  • back up or restore application settings

and the tea on storage: the on-disk database format is identical to the one used by the GUI, and it's encrypted with AES-256-GCM using an Argon2id-derived key. so yes, your secrets are locked up tighter than your finsta. 🔐✨

💅 OPTIONS 💅

🎯 Actions

okay so the rules are the rules: exactly one action must be supplied on each invocation. one. not two. not zero. pick one, bestie. 👑
  • -s, --show — show the OTP for one or more tokens. she needs --account or --issuer to know who you're talking about, so don't leave her guessing. 🌟
  • -l, --list — list every token in the database — that's the account, the issuer, and the group. the whole roster. 📋
  • --list-databases — print the list of known databases from the configuration. your database IRLs, basically.
  • --list-types — print the import/export type identifiers that --type will actually accept. check this before you come for her with a made-up format name. 😭
  • --import — import tokens from a backup file. requires --type and --file. both of them, no skipping. 🌈
  • --export — export tokens to a backup file. requires --type.
  • --export-settings — print the application settings (GSettings) as JSON, or write them to the file given via --file. your choice, main character. ✨
  • --import-settings — restore application settings from the JSON file given via --file. glow-up restored. 💖
  • -v, --version — print the version and exit. short, sweet, slays. 👑

🔍 Selection

  • -d, --database DB — path to the database, or a database name as printed by --list-databases. when you omit it, the default database from the configuration gets used. she's got a fave and it's in your config. 💜
  • -a, --account ACCOUNT — account label to match (used with --show).
  • -i, --issuer ISSUER — issuer to match (used with --show).
  • -m, --match-exact — match --account and --issuer with case-sensitive equality instead of the default case-insensitive contains-style comparison. so default is chill and fuzzy, -m is precise and picky. no in-between. 🎯
  • -n, --show-next — also print the OTP that will become valid after the current period. she's showing you the future, bestie. 🔮 has no effect for HOTP tokens though — HOTP doesn't do periods, so this one just sits there politely doing nothing. 💀

📥📤 Input / output

  • -t, --type TYPE — backup format identifier. use --list-types to see the accepted values. don't guess, just look. 🙈
  • -f, --file PATH — backup file to import, or settings file to write/read. depends on which action you're on, iykyk.
  • -o, --output-dir DIR — destination directory for --export. defaults to the user's home directory. not available in the Flatpak build — so if you're on Flatpak, this option literally ghosted you. 👻
  • -p, --password-file PATH — read the database decryption password from the first line of PATH instead of prompting on stdin. ngl this is the convenient one. BUT: the file must be a regular file (not a symlink) with mode 0600 or stricter. symlinks and loose permissions? absolutely not. 🚫🔒
  • --output=FORMAT — output format for --show, --list, and --list-databases. accepted values: table (that's the default, btw), json, or csv. JSON output is a single document; CSV output starts with a header row. pick your fighter. 📊

🌈 EXAMPLES 🌈

List every account/issuer pair in the default database:

otpclient-cli --list

Print the current OTP for an account, plus the next one:

otpclient-cli --show -a alice -n

Get the current OTP as a JSON object for scripting:

otpclient-cli --show -a alice --output=json

Import an Aegis encrypted backup:

otpclient-cli --import --type aegis_enc --file aegis.json

Export to a 2FAS plain backup in /tmp:

otpclient-cli --export --type twofas_plain -o /tmp

Use a passphrase file (chmod 0600) instead of stdin:

otpclient-cli --show -a alice -p ~/.config/otpclient/passphrase

⭐ EXIT STATUS ⭐

otpclient-cli exits with 0 on success and a non-zero status on error. and bestie, the error list is giving: incorrect password, missing file, malformed input, etc. 😭 the specific error messages get written to standard error, so they'll show up right in your terminal where you can see them. 💌

🎀 FILES 🎀

  • ~/.config/otpclient/otpclient.cfg — the configuration file holding the default database path. this is where your fave database lives. 🏠💖

🫶 SEE ALSO 🫶

💀 BUGS 💀

found a bug? not her fault, but she wants to know. report issues at https://github.com/paolostivanin/OTPClient/issues — go tell the devs, they're listening. 🐛✨

okay that's the whole page, you ate that. 🍓

this was brought to you by otpclient-cli, from the OTPClient Manual, dated May 2026. go forth and OTP responsibly, bestie. 💅👑🦋

📦 where this page comes from