Metadata-Version: 2.4
Name: authenticator-tui
Version: 1.1.0
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

A fast, keyboard-driven terminal client for TOTP/HOTP codes — live-refreshing codes, filtering, add/delete/export, a big-code view, and clipboard copy.

See [features.md](features.md) for the full feature list, file discovery behavior, and keybindings.

## 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, it looks for `otp.txt` in the current directory, then
`~/.config/authenticator-tui/otp.txt` (created automatically if neither exists),
then shows a file picker to confirm. The file is auto-saved on every add or delete.
See [features.md](features.md) for details and the full keybindings list.

## 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 .
```
