Application Behavior

This page summarizes the current CLI and early Textual UI behavior. For complete command options, see the CLI reference.

Vault selection

Commands use ~/.desktop-2fa/vault by default. Choose a different file with the global --vault option or set DESKTOP_2FA_VAULT. The command-line option takes precedence.

Vault creation

Only vault init, list and add create a missing vault. Other content commands report a missing-vault error; a failed load never triggers creation. In non-interactive use, supply --password or --password-file.

The d2fa ui prototype does not create missing vaults.

Authentication and passwords

Commands that access vault contents require a password. Weak passwords are evaluated with zxcvbn and can be warned about or rejected through configuration. Password changes are managed with d2fa vault change-password.

Entry selection and terminal UI

Code, remove and rename use case-sensitive exact account names before a unique issuer fallback. Ambiguous matches fail with status 6. Rename refuses an occupied destination; list --indices and rename OLD NEW --index N support explicit repair of legacy duplicates.

Textual shows validity using the selected account's actual period. Expired codes are cleared, changing selection clears the previous result, and copied-code feedback shows the current value and remaining validity. Entry management remains in the CLI.

Errors and state changes

The CLI distinguishes missing vaults from filesystem permission failures, validates vault files before loading, and uses atomic replacement for saves. Check the command output and exit status before assuming an operation succeeded.

These details can evolve; the changelog and upstream README are the source of truth.