passtui 0.0.5b1

The TUI for pass

PassTUI

The TUI for pass — the standard Unix password manager.

---

About The Project

PassTUI is a terminal user interface for pass — the standard Unix password manager. It brings a keyboard-driven, visual experience to your encrypted password store without ever leaving the terminal.

If you live in the terminal and want a fast, intuitive way to manage your GPG-encrypted passwords, PassTUI is for you.

Built With

(back to top)

---

Features

• Browse your password store in a tree view
• Search / filter passwords in real time
• View and edit password entries in a built-in editor
• Copy password to clipboard with a single keystroke
• Copy username to clipboard with a single keystroke
• Copy any line to clipboard
• Create a new GPG key and password store
• Add new password entries
• Sync the password store with a remote Git repository
• Export your GPG key to a file
• Import a GPG key and re-encrypt the store

(back to top)

---

Getting Started

Prerequisites

pass relies on GPG to encrypt and decrypt passwords, so gpg must be installed on your system.

Ubuntu / Debian

sudo apt install gnupg

CentOS / Fedora

sudo yum install gnupg

openSUSE

sudo zypper install gpg2

Gentoo

emerge --ask app-crypt/gnupg

Arch

sudo pacman -Syu gnupg

macOS

macOS doesn’t include a default GPG configuration. I’ve provided a script that handles the most common setup steps, but if it doesn’t work in your case, you’ll need to install the prerequisites manually.

curl -LsSf https://raw.githubusercontent.com/fjmoralesp/passtui/main/scripts/install.sh | sh

Click to see manual installation instructions

1. Install gnupg and pinentry-mac: brew install gnupg pinentry-mac
2. Create the keyring folder: gpg -k
3. Configure pinentry: echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" > "$HOME/.gnupg/gpg-agent.conf"
4. Add GPG terminal detection to your shell config (~/.zshrc or ~/.bashrc): export GPG_TTY=$(tty)
5. Create a gpg2 binary symlink: ln -s "$(which gpg)" "$(brew --prefix)/bin/gpg2"
6. Restart the GPG agent: gpgconf --kill gpg-agent

Installation

Install PassTUI with uv

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install passtui:

uv tool install --python 3.14 passtui

Then launch it:

passtui

(back to top)

---

Usage

Create a GPG Store

If you don't have a password store yet, PassTUI can create a GPG key and initialise the store for you in one step.

1. Launch PassTUI: passtui
2. Press g to open the Create GPG Store dialog
3. Fill in your name, email
4. Press Enter to confirm

PassTUI will generate a 4096-bit RSA GPG key and initialise the store at ~/.password-store (or the path you provided).

Tip: The store path defaults to ~/.password-store. You can also set the PASSWORD_STORE_DIR environment variable to point to a different location before launching PassTUI.

(back to top)

Add a New Password

1. Press n to open a blank entry in the editor

2. Fill in your password, username, URL, and any extra notes following the template:

   (your password)
   Username: your-username
   Url: https://example.com
   

3. Press Ctrl+S to save

4. When prompted, enter the path for the new entry (e.g., email/gmail)

Tip: The first line is always the password. PassTUI (and pass) will copy only the first line when you use the copy-password shortcut.

(back to top)

View an Existing Password

1. Navigate the tree with j / k (or arrow keys)
2. Expand a folder with Enter
3. Select an entry — its decrypted contents will appear in the editor panel on the right
4. Press e to move focus to the editor
5. From the editor you can:
   • Press c to copy the password to the clipboard
   • Press b to copy the username to the clipboard
   • Press y to copy the current line to the clipboard
   • Press i to enter edit mode and make changes
   • Press Ctrl+S to save any edits

(back to top)

Sync with a Git Repository

PassTUI can push and pull your password store to/from a remote Git repository.

First-time setup (new store)

1. Press s to trigger a sync
2. When prompted, enter the remote repository URL (e.g., [e-mail]:user/passwords.git)
3. PassTUI will initialise a Git repo, add the remote, and push

Subsequent syncs (store already has Git)

1. Press s
2. PassTUI will pull with rebase and then push automatically

Note: This workflow is designed for stores that were created fresh. If your store was cloned from an existing remote, manage Git operations outside of PassTUI for the initial setup.

(back to top)

Export a GPG Key

Exporting your GPG key lets you back it up or transfer it to another machine.

1. Press x to open the Export GPG Key dialog
2. Enter your GPG key passphrase
3. Optionally enter a custom output path (defaults to ~/passtui/gpg-export.asc)
4. Press Enter to export

The key will be saved as an ASCII-armored .asc file.

Warning: Keep this file in a safe place. Anyone who has it and knows your passphrase can decrypt your passwords.

(back to top)

Import a GPG Key

Importing a GPG key allows you to move your password store to a new machine or add a new trusted key.

1. Press z to open the Import GPG Key dialog
2. Enter the path to the .asc key file (e.g., ~/passtui/gpg-export.asc)
3. Press Enter to import

PassTUI will import the key, mark it as ultimately trusted, update the store's .gpg-id, and re-encrypt all entries with the new key.

(back to top)

---

Keybindings

Global

Key	Action
/	Focus the search bar
n	Add a new password entry
e	Focus the editor panel
t	Focus the password tree
s	Sync with Git
g	Create a new GPG Store
x	Export GPG key
z	Import GPG key

Password Tree (T panel)

Key	Action
j / ↓	Move cursor down
k / ↑	Move cursor up
h	Scroll left
l	Scroll right
Enter	Expand folder / select entry
c	Copy password to clipboard
b	Copy username to clipboard

Editor (E panel)

Key	Action
i	Enter edit mode
Escape	Cancel / exit edit mode
j	Move cursor down
k	Move cursor up
h	Move cursor left
l	Move cursor right
c	Copy password to clipboard
b	Copy username to clipboard
y	Copy current line to clipboard
Ctrl+S	Save changes

(back to top)

---

Roadmap

• Config file
• Vi motions for password editor
• Custom keybindings
• Imports
  • 1Password txt or 1pif data
  • KeePass KeepassX XML / CSV data
  • Figaro's Password Manager XML data
  • LastPass CSV data
  • Ked Password Manager data
  • Revelation Password Manager data
  • Password Gorilla data
  • PWSafe data
  • KWallet data
  • Roboform data
  • password-exporter data
  • pwsafe data

See the open issues for a full list of proposed features and known issues.

(back to top)

---

Contributing

Contributions, issues, and pull requests are welcome! See CONTRIBUTING.md for development setup instructions.

(back to top)

---

License

Distributed under the GNU General Public License v3. See LICENSE for more information.

(back to top)

---

Contact

Francisco Morales — [e-mail]

Project Link: https://github.com/fjmoralesp/passtui

(back to top)

---