Metadata-Version: 2.4
Name: authenticator-tui
Version: 1.0.1
Summary: A keyboard-driven terminal UI for managing TOTP/HOTP one-time passwords
Project-URL: Homepage, https://gitlab.com/riphixel/authenticator-tui
Project-URL: Repository, https://gitlab.com/riphixel/authenticator-tui
Project-URL: Issues, https://gitlab.com/riphixel/authenticator-tui/-/issues
Author-email: Pierre Gronlier <pierre@gronlier.fr>
License-Expression: MIT
License-File: LICENSE
Keywords: 2fa,authenticator,hotp,mfa,otp,terminal,textual,totp,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: pyotp>=2.10.0
Requires-Dist: pyperclip>=1.11.0
Requires-Dist: textual>=8.2.7
Description-Content-Type: text/markdown

# authenticator-tui

[![pipeline status](https://gitlab.com/riphixel/authenticator-tui/badges/main/pipeline.svg)](https://gitlab.com/riphixel/authenticator-tui/-/commits/main)
[![coverage report](https://gitlab.com/riphixel/authenticator-tui/badges/main/coverage.svg)](https://gitlab.com/riphixel/authenticator-tui/-/commits/main)
[![Latest Release](https://gitlab.com/riphixel/authenticator-tui/-/badges/release.svg)](https://gitlab.com/riphixel/authenticator-tui/-/releases)


A terminal UI for managing TOTP/HOTP one-time passwords stored as `otpauth://` URLs.

<img width="700" src="https://gitlab.com/riphixel/authenticator-tui/-/raw/main/screenshots/main.svg" alt="Main screen">

## Features

- **Live codes** — TOTP codes refresh every second with a countdown progress bar
- **Filter** — press `f` and type to narrow the list by issuer or account
- **Add** — paste an `otpauth://` URL or fill in fields manually
- **Delete** — remove an entry with auto-save
- **Big code view** — press Enter on any entry to display the code in large digits
- **Clipboard** — click any entry to copy the code
- **Export** — write all entries to a file as `otpauth://` URLs

## Install

Install as a global CLI tool from [PyPI](https://pypi.org/project/authenticator-tui/):

```bash
uv tool install authenticator-tui
```

Or with pip:

```bash
pip install --user authenticator-tui
```

Or run directly without installing:

```bash
uvx authenticator-tui otp.txt
```

To install the latest development version from source instead:

```bash
uv tool install git+https://gitlab.com/riphixel/authenticator-tui
```

## Usage

```bash
authenticator-tui [path/to/otp.txt]
```

If no file is given (or the path doesn't exist) a file picker appears on startup.
The file is auto-saved on every add or delete.

## Keybindings

| Key | Action |
|---|---|
| `f` | Focus filter input |
| `↓` in filter | Jump to first list entry |
| `↑` on first entry | Jump back to filter |
| `a` | Add OTP (modal) |
| `d` | Delete selected OTP |
| `e` | Export to file (modal) |
| Enter | Show code in big digits |
| Click | Copy code to clipboard |
| Escape | Clear filter / close modal |
| `q` | Quit |

## Screenshots

### Filter

<img width="700" src="https://gitlab.com/riphixel/authenticator-tui/-/raw/main/screenshots/filter.svg" alt="Filter">

### Add OTP

<img width="700" src="https://gitlab.com/riphixel/authenticator-tui/-/raw/main/screenshots/add_modal.svg" alt="Add OTP modal">

### Big code view

<img width="700" src="https://gitlab.com/riphixel/authenticator-tui/-/raw/main/screenshots/big_code.svg" alt="Big code">

## File format

One `otpauth://` URL per line. Blank lines and lines starting with `#` are ignored.

```
otpauth://totp/GitHub:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub
otpauth://totp/PayPal:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=PayPal
```

## Development

```bash
uv sync
uv run authenticator-tui otp.txt

# tests
uv run pytest

# lint
uvx ruff check .
uvx ruff format --check .
```
