2fas

2fas Python

2fas-python is an unofficial implementation of 2FAS - the Internet’s favorite open-source two-factor authenticator. It consists of a core library in Python and a CLI tool.

Installation

To install this project, use uvenv (recommended), pipx, uv or pip:

uvenv install 2fas
# or:
uv tool install 2fas
# or:
pipx install 2fas
# or:
pip install 2fas

Usage

To see all available options, you can run:

2fas --help

If you simply run 2fas or 2fas /path/to/file.2fas, an interactive menu will show up. If you only want a specific TOTP code, you can run 2fas <service or 2fas /path/to/file.2fas <service. Multiple services can be specified: 2fas <service1 <service2 [/path/to/file.2fas]. Fuzzy matching is applied to (hopefully) catch some typos. You can run 2fas --all to generate codes for all TOTP in your .2fas file.

Settings

# see all settings:
2fas --settings # shortcut: -s
# see a specific setting:
2fas --setting key
# update a setting:
2fas --setting key value

This can also be done from within the interactive menu. 2fas cli settings are stored in ~/.config/2fas/config.toml and contain the following settings:

[tool.2fas]
files = [
    "/some/path/to/file.2fas",
    ... # list of known files, used by 'set default file' in the settings menu
]
default_file = "/some/path/to/file.2fas" # which file to use when no .2fas file was explicitly passed?
auto_verbose = true # run every command as if --verbose was passed?

unlock_method = "password" # or "security-key"
password_unlock_policy = "os-session" # how often to ask for your passphrase
security_key_unlock_policy = "process" # how often to ask for a touch

If your settings file is still at an older location (~/.config/2fas.toml), it is moved into place the first time you run 2fas. The directory also holds keys/, used by the security key support below.

Unlocking your vault

Your .2fas file is encrypted with a key derived from your passphrase (PBKDF2-HMAC-SHA256, 10 000 iterations - that number is fixed by the 2FAS file format, so a strong passphrase is what actually protects the file). 2fas never writes to your .2fas file; it only ever reads it.

An unlock method and two policies control unlocking, and the policies are separate on purpose.

unlock-method is how you unlock: password (the default) or security-key.