dotp 0.1.1

Dank One Time Password - CLI and TUI TOTP/Authenticator storage

DOTP

Dank One Time Password - A CLI and TUI application for secure TOTP/Authenticator storage.

Features

• Encrypted vault storage with password protection
• CLI commands for managing TOTP entries
• Interactive TUI for quick access
• Import/Export support for Aegis and otpauth URI formats
• Real-time token generation with auto-refresh
• Search and filter capabilities with fuzzy matching
• Clipboard integration
• Clean, modern terminal UI with progress indicators

Installation

Using uvx (Recommended)

Run DOTP without installation:

uvx dotp --help

Global install

uv tool install dotp

Pip install

pip install dotp

Using uv (for development)

git clone https://github.com/rochacbruno/dotp.git
cd dotp
uv sync
uv run dotp --help

Quick Start

Initialize a vault

uvx dotp init

This creates an encrypted vault at ~/.config/dotp/.vault.dotp (or $XDG_CONFIG_HOME/dotp/.vault.dotp).

Add an entry

uvx dotp add --label GitHub --secret YOURBASE32SECRET

Or interactively:

uvx dotp add --label GitHub
# You'll be prompted for the secret

List all entries

uvx dotp list

Get a specific token

uvx dotp get GitHub

For scripting (clean output):

DOTP_PASSWD=123456 uvx dotp get GitHub | wl-copy

Import from file

DOTP supports importing from various formats. See the sample files in the repository:

• otpauth_sample.txt - Example otpauth URI format
• aegis_sample.json - Example Aegis export format

# From otpauth URI format
uvx dotp import otpauth_sample.txt

# From Aegis JSON format
uvx dotp import aegis.json --aegis

Export to file

# To otpauth URI format
uvx dotp export backup.txt

# To Aegis JSON format
uvx dotp export backup.json --aegis

TUI Mode

Launch the interactive TUI by running dotp without arguments:

uvx dotp
# or with password from environment
DOTP_PASSWD=123456 uvx dotp

TUI Features

• Type to search: Start typing to filter entries in real-time
• Enter in search: Focus results to navigate with arrow keys
• Enter on item: Copy selected token to clipboard
• Ctrl+Enter: Copy token and close application
• Ctrl+A: Add a new entry
• Ctrl+Q: Quit
• Escape: Clear search
• Backspace: Return to search when navigating results

Configuration

Create a config file at ~/.config/dotp/config.toml:

# Path to your vault file (optional)
vault_path = "/path/to/.vault.dotp"

# Close TUI immediately after copying (default: false)
close_on_copy = true

# Clipboard command to use (default: wl-copy)
clipboard_command = "wl-copy"

Environment Variables

• DOTP_PASSWD: Set vault password (useful for scripting)

Vault Location Priority

DOTP looks for the vault in this order:

1. --path argument
2. vault_path in config file
3. .vault.dotp in current directory
4. ~/.config/dotp/.vault.dotp

Security

• Vault is encrypted using Fernet (symmetric encryption)
• Password is derived using PBKDF2HMAC with SHA256
• 480,000 iterations (OWASP recommended minimum)
• 16-byte random salt per vault

Development

Running tests

uv sync --extra dev
uv run pytest

Running with coverage

uv run pytest --cov=src/dotp --cov-report=html

Linting

uvx ruff check src/
uvx ruff format src/

Stack

• UV - Package management
• pyotp - TOTP generation
• cyclopts - CLI framework
• Rich - Terminal formatting
• Textual - TUI framework
• cryptography - Encryption
• xdg-base-dirs - XDG Base Directory support

License

AGPL License - See LICENSE file for details