table of contents
- Tumbleweed 5.3.2-1.1
- Leap-16.0
| OTPCLIENT-CLI(1) | OTPClient Manual | OTPCLIENT-CLI(1) |
NAME¶
otpclient-cli - command-line interface for OTPClient
SYNOPSIS¶
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. It can show one-time passwords, list the contents of a database, import or export tokens in any of the supported formats, and back up or restore application settings. The on-disk database format is identical to the one used by the GUI and is encrypted with AES-256-GCM using an Argon2id-derived key.
OPTIONS¶
Actions¶
Exactly one action must be supplied on each invocation.
- -s, --show
- Show the OTP for one or more tokens. Requires --account or --issuer.
- -l, --list
- List every token in the database (account, issuer, group).
- --list-databases
- Print the list of known databases from the configuration.
- --list-types
- Print the import/export type identifiers accepted by --type.
- --import
- Import tokens from a backup file. Requires --type and --file.
- --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.
- --import-settings
- Restore application settings from the JSON file given via --file.
- -v, --version
- Print the version and exit.
Selection¶
- -d, --database DB
- Path to the database, or a database name as printed by --list-databases. When omitted, the default database from the configuration is used.
- -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.
- -n, --show-next
- Also print the OTP that will become valid after the current period. Has no effect for HOTP tokens.
Input / output¶
- -t, --type TYPE
- Backup format identifier. Use --list-types to see the accepted values.
- -f, --file PATH
- Backup file to import or settings file to write/read.
- -o, --output-dir DIR
- Destination directory for --export. Defaults to the user's home directory. Not available in the Flatpak build.
- -p, --password-file PATH
- Read the database decryption password from the first line of PATH instead of prompting on stdin. The file must be a regular file (not a symlink) with mode 0600 or stricter.
- --output=FORMAT
- Output format for --show, --list, and --list-databases. Accepted values: table (default), json or csv. JSON output is a single document; CSV output starts with a header row. Diagnostics go to stderr. HOTP counters are saved before output; the counter field contains the next unused counter, matching the GUI.
Partial token imports report invalid and duplicate counts. Valid records are imported with exit status zero and warnings on stderr; entirely invalid input fails without changing the database. Migration exports do not update database backup reminders.
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_encrypted --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 (incorrect password, missing file, malformed input, etc.). Specific error messages are written to standard error.
FILES¶
- ~/.config/otpclient/otpclient.cfg
- Configuration file holding the default database path.
SEE ALSO¶
BUGS¶
Report issues at https://github.com/paolostivanin/OTPClient/issues
| October 2026 | otpclient-cli |