proton-authenticator-cli

Unofficial Proton Authenticator command-line client with cloud sync.

Authenticates with Proton, unlocks your Authenticator Key, syncs encrypted TOTP/Steam entries, and generates codes from the CLI. Includes an interactive TUI.

Not an official Proton product. For the supported apps, use Proton Authenticator. Not affiliated with Proton AG.

Install

Requires Bun ≥ 1.1 at runtime (including when you install with npm).

Bun

bun add -g proton-authenticator-cli

Or from GitHub:

bun install -g github:brandonkramer/proton-authenticator-cli

npm

npm install -g proton-authenticator-cli

Run

protonauth                 # interactive TUI (TTY only)
protonauth status --output json   # agent / scripting
protonauth --help

From a clone

git clone https://github.com/brandonkramer/proton-authenticator-cli.git
cd proton-authenticator-cli
bun install
bun link                   # optional: puts `protonauth` on your PATH

Requirements

• Bun ≥ 1.1
• Proton account in Single Password Mode
• TOTP if you use 2FA (FIDO2/security keys are not supported)
• Optional: Proton Pass CLI for account password injection
• macOS for interactive CAPTCHA (native WKWebView helper; built on postinstall when possible)

Usage

Interactive TUI

protonauth
# or
protonauth tui

↑↓ + Enter to choose · number shortcuts · q / Esc to quit.

Commands

protonauth signin [username]
protonauth signin --pass "pass://Personal/Proton Account"
protonauth signout
protonauth sync
protonauth list
protonauth list --type totp
protonauth code github
protonauth status

Proton Pass (recommended)

# Option A: Pass item ref
protonauth signin --pass 'pass://Personal/Proton Account'

# Option B: pass-cli run
export PROTON_PASSWORD='pass://Personal/Proton Account/password'
export PROTON_TOTP='pass://Personal/Proton Account/totp'   # optional
pass-cli run -- protonauth signin

Env aliases: PROTONAUTH_PASS, PROTON_USERNAME, PROTON_PASSWORD, PROTON_TOTP.

Agents / automation

export PROTONAUTH_AGENT=1          # or CI=1 — no TUI, default --output json
# Human once (CAPTCHA / first 2FA):
protonauth signin --pass 'pass://Personal/Proton Account'

# Then:
pass-cli run -- protonauth sync --output json
protonauth list --type totp --output json
pass-cli run -- protonauth code github --output json
protonauth status --output json

• --output json|plain|ink (or PROTONAUTH_OUTPUT)
• Non-interactive: no Ink prompts; missing password/TOTP/query → structured error codes
• CAPTCHA: never opens a window in agent mode (captcha_required — sign in interactively once)
• No-args / tui refused when PROTONAUTH_AGENT, CI, or non-TTY stdin (exit 2)

Security

• Honest client headers: {macos|linux|windows}-authenticator@… (no android/ios spoofing)
• Config dir ~/.config/proton-authenticator-cli is 0700, files 0600
• Account password is never persisted — use Proton Pass or a prompt
• Authenticator entry secrets stay encrypted on disk; decrypted only in memory for code / sync

CAPTCHA

Proton may require a CAPTCHA on /auth (API code 9001). On macOS, protonauth signin opens a floating native WKWebView window.

Solve the CAPTCHA in that native window — not in Safari/verify.proton.me. Completing verification in a normal browser does not return a token to the CLI.

bun run build:captcha   # if postinstall skipped it; needs Xcode CLT
protonauth signin

License

GPL-3.0-or-later — see LICENSE.