← Back to documentation

CLI Reference

Desktop-2FA's command-line interface manages TOTP entries and encrypted vaults. Use d2fa --help or d2fa COMMAND --help for the installed version's complete options.

Common commands

# Create a vault
d2fa vault init

# Add an entry interactively (hidden Secret prompt)
d2fa add

# List entries and generate a code
d2fa list --indices
d2fa code GitHub

# Copy the generated code to the clipboard
d2fa code GitHub --copy

# Manage vault passwords and find the selected vault
d2fa vault unlock
d2fa vault change-password
d2fa vault path

Command groups

  • add, list, rename, remove — manage TOTP entries.
  • code — generate a code; supports --copy, --copy-only, --json, --raw, and --quiet.
  • vault init (also available as init-vault), vault unlock, vault change-password, vault path — manage the vault.
  • backup, export, import — create and move encrypted vault copies.
  • ui — launch the early Textual terminal UI prototype.

Adding accounts and selecting entries

Interactive d2fa add hides input at the dedicated Secret prompt. Enter a plain issuer there first: the issuer prompt remains visible. Secrets or full URIs passed as command arguments can appear in shell history or process inspection.

URI add preserves algorithm, digits and period. Quote the entire URI so the shell preserves ampersands. This example uses a public synthetic secret:

d2fa add "otpauth://totp/Example:demo?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA256&digits=8&period=60"

Names are case-sensitive. An exact account name takes priority; otherwise a unique issuer match is accepted. Ambiguous matches fail with status 6. For legacy duplicates, run d2fa list --indices, then d2fa rename OLD NEW --index N. The index is one-based and changes when list order changes. Rename updates both account name and issuer and refuses an occupied account name.

Output and exit statuses

code --json writes one success or error object to stdout. --raw prints only the code on success. Diagnostics and password prompts use stderr. --quiet suppresses both streams and requires a supplied password or password file; the exit status is preserved.

  • 0: success; 1: filesystem, corrupted data or unsupported format failure.
  • 2: authentication failure; 3: missing entry; 4: missing vault.
  • 5: clipboard failure; 6: validation failure, ambiguity, refused overwrite or write conflict.

CLI import/export uses encrypted D2FA v1 files. External-format Python adapters are separate helpers, not CLI import modes. Export preserves an existing destination unless --force is supplied; source aliases and destination symlinks are refused even with force.

Global options

  • --vault PATH — select a vault file; place this before the command.
  • --password PASSWORD or --password-file PATH — supply a vault password.
  • --allow-weak-passwords — bypass interactive weak-password checks when creating a vault or changing its password. D2FA_ALLOW_WEAK_PASSWORDS=1 has the same effect.
  • --version, --help — display version or help.

--vault takes precedence over DESKTOP_2FA_VAULT. If neither is set, the default is ~/.desktop-2fa/vault.

Non-interactive use

For scripts, prefer --password-file to avoid putting a password in shell history or process arguments. Protect the password file with appropriate filesystem permissions.

d2fa --password-file /path/to/passphrase.txt list

Password files contain exactly one UTF-8 line without a BOM. Only one optional final LF or CRLF is removed; spaces and tabs remain significant. Empty, multiline, bare-CR, BOM and invalid UTF-8 input is rejected. Older files relying on automatic trimming may need to be corrected to contain the actual password previously used.

Textual UI status

d2fa ui is an early prototype. It can list vault entries, generate codes, and copy codes. It does not manage entries or create a missing vault. The CLI remains the primary interface.