TwoFac Open Source, Native, Cross-Platform 2FA App for Watch, Mobile, Desktop, Web and CLI!

ROADMAP

• Common functionality
  • Add new accounts
  • Display accounts with 2FA codes
  • Save accounts to a storage
  • Delete account storage
  • Backup & Restore via a backup transport
  • Export & Import accounts (encrypted with passkey)
  • QR Account Scanning (Camera + Clipboard)
  • Import from other 2FA apps
    • Authy (JSON format)
    • 2FAS (JSON format)
    • Ente (plaintext otpauth:// URIs)
• Mobile Apps (Android & iOS)
  • Biometric Authentication
  • Home / Accounts / Settings Bottom Tabs
• Wearable Apps
  • Wear OS companion app with offline sync
  • watchOS companion app with offline sync
• Desktop App
  • System Tray / Menu Bar Application
• Web & Browser Extensions
  • Progressive Web App (PWA)
  • Chrome Extension
  • Firefox Extension
  • WebAuthn / Device-Credential Unlock
• CLI App
  • Add new accounts
  • Display 2FA codes with auto-refresh
  • Delete account storage

Documentation

• Importing from Other Apps - Guide to importing 2FA secrets from Authy, 2FAS, Ente Auth, and other authenticator apps
• Development Guide - Setup, building, and running the project
• GitHub Copilot Setup - Pre-configured environment with Java 21, Node.js 22, and Gradle caching

Development

Prerequisites

• JDK 17+ (recommended: JDK 21)
• Android SDK (if building Android targets)
• Xcode (if building iOS targets on macOS)
• Native toolchains for your platform (GCC/Clang for Linux, MSVC for Windows)

Project structure

See AGENTS.md for the full module map, dependency direction, and platform-to-module routing — it is the single source of truth for contributor guidance.

TwoFac/
├── sharedLib/    # Shared 2FA library (TOTP/HOTP, crypto, storage)
├── cliApp/       # CLI application (Clikt-based, native binaries)
├── composeApp/   # Compose Multiplatform UI application
├── watchApp/     # Wear OS app
└── iosApp/       # iOS application wrapper

Common commands

# Baseline checks
./gradlew check

# Module tests
./gradlew :sharedLib:test
./gradlew :cliApp:allTests
./gradlew :composeApp:test

# Run desktop app
./gradlew :composeApp:run

# Run web app
./gradlew :composeApp:wasmJsBrowserDevelopmentRun

CLI usage (dual mode)

2fac now supports two run modes:

• Interactive TUI mode: run 2fac in an interactive terminal
• One-shot CLI mode: run explicit subcommands

When 2fac is run without subcommands in a non-interactive terminal, it prints help and exits.

2fac
  display
  info
  accounts
    add
    remove
  storage
    --use-backend <standalone|common>
    clean
    delete
    reinitialize
    backup
      export
      import

Migration notes

• Root-level commands 2fac add ... and 2fac backup ... were removed.
• Use 2fac accounts add ... and 2fac storage backup ... instead.