Skip to content

Getting Started

Jump to bottom
Cristhian Melo edited this page Jul 20, 2026 · 1 revision

Getting Started

1. Install

Prebuilt binaries — download from GitHub Releases. Archives, MSI (Windows), and shell installers are available for Linux, macOS, and Windows.

From crates.io:

cargo install rpass-cli

The installed binary is rpass.

2. Install GnuPG

rpass delegates all encryption to your system's GnuPG installation.

Platform Command
macOS brew install gnupg
Ubuntu/Debian sudo apt install gnupg
Fedora/RHEL sudo dnf install gnupg2
Windows Install Gpg4win

Verify: gpg --version should print gpg (GnuPG) 2.x.

3. Set up a GPG key

If you already have a GPG key you want to use, skip this step.

gpg --full-generate-key

Choose RSA and RSA, 4096 bits, and enter your name and email. When done, find your key ID:

gpg --list-secret-keys --keyid-format LONG

The key ID is the long hex string after rsa4096/, or you can use the email you registered.

4. Initialize the store

rpass init you@example.com

This creates ~/.password-store/.gpg-id with your key ID. All entries in the store will be encrypted for that key.

Use a custom directory:

rpass --store-dir ~/my-store init you@example.com

Or set the environment variable permanently:

export PASSWORD_STORE_DIR=~/my-store

Multiple recipients (e.g. you + a team member):

rpass init you@example.com teammate@example.com

Both of you can decrypt any entry. Each person uses their own private key.

Subfolder recipients (different key for a specific folder):

rpass init --path work work-key@example.com

Entries under work/ will be encrypted for work-key@example.com instead of the root recipient.

5. Add your first entry

Interactive prompt:

rpass insert email/work

rpass will ask for the password (input is hidden).

Multiline entry (password on first line, metadata below):

s3cr3t-p4ssword
username: alice
url: https://mail.example.com

From stdin (non-interactive):

echo "my-password" | rpass insert email/work

6. Retrieve an entry

rpass show email/work

Output:

s3cr3t-p4ssword
username: alice
url: https://mail.example.com

As JSON:

rpass show email/work --json
{
  "entry": "email/work",
  "password": "s3cr3t-p4ssword",
  "fields": [
    { "name": "username", "value": "alice" },
    { "name": "url", "value": "https://mail.example.com" }
  ]
}

7. List entries

rpass list
rpass list --json

8. Other common commands

rpass generate email/work        # generate a random 14-character password
rpass edit email/work            # open entry in $EDITOR
rpass mv email/work archive/work # move or rename
rpass rm email/work              # remove
rpass otp email/totp             # generate TOTP code (entry must have otpauth:// line)

9. Git integration

rpass commits automatically after every write command. To run git commands manually:

rpass git status
rpass git log
rpass git remote add origin git@github.com:you/pass-store.git
rpass git push

10. Shell completions

rpass completions bash >> ~/.bashrc
rpass completions zsh > "${fpath[1]}/_rpass"
rpass completions fish > ~/.config/fish/completions/rpass.fish
rpass completions powershell >> $PROFILE

11. Check your setup

rpass doctor

Reports GPG version, store location, key availability, and git status.

Non-interactive / headless use

For scripts and CI, pass the GPG passphrase via stdin:

printf 'my-gpg-passphrase\n' | rpass show email/work --json --passphrase-stdin

Clone this wiki locally