Vault Guide

The vault is a local encrypted file containing TOTP secrets. Commands that read or modify its contents require password authentication.

Vault location

The default path is ~/.desktop-2fa/vault. Select a different file before a command with --vault, or set DESKTOP_2FA_VAULT. An explicit option takes precedence over the environment variable.

d2fa --vault ./work-vault list
d2fa --vault ./work-vault vault path

Create and access a vault

d2fa vault init
d2fa list

Only vault init, list and add create missing vaults. Other content commands report a missing-vault error. A failed load never triggers creation. In non-interactive use, provide a password with --password or --password-file. The early d2fa ui prototype does not create a missing vault.

Password management

Use d2fa vault unlock to verify the password and d2fa vault change-password to change it. Interactive password creation and changes are evaluated with zxcvbn; by default weak passwords trigger a warning and confirmation, and configuration can reject them. See the security guide for the scope of these checks.

There is no password recovery mechanism. Keep a secure copy of your password.

Backups and migration

Backups are explicit, not automatic. Before upgrading, create an encrypted backup:

d2fa backup

Use d2fa export PATH and d2fa import PATH to move a vault. Protect exported files and backups as carefully as the original vault.

Export preserves existing destinations unless explicitly given --force. Source aliases and destination symlinks are refused even with force. Import into a separate vault when checking recovery:

d2fa export ./backup.d2fa
d2fa --vault ./recovered-vault import ./backup.d2fa

Concurrent edits and compatibility

Version 0.10.0 keeps the D2FA v1 format and cryptographic parameters unchanged. Saves reject stale revisions or busy publication locks with status 6: reload before retrying. Empty .NAME.lock sidecars intentionally remain beside vaults. File symlinks and multiply linked vault files are read-only.

Password files now preserve spaces and tabs and accept one UTF-8 line without a BOM. If an older password file relied on trimming, correct it to contain the actual previously used password; there is no automatic fallback or vault migration.

File handling and compatibility

The application accepts regular vault files up to 10 MiB and uses atomic replacement when saving. Normal CLI and Textual UI vault flows continue to require a non-empty password. However, the version 0.9.0 public Python API no longer opens vaults created by earlier API versions without a password. If this affects your vault, use the previous release to open it and re-save it with a non-empty password before upgrading; make a backup before migrating.

See the upstream vault lifecycle notes for current project guidance.