Skip to content

Data Organization

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

Data Organization

Entry format

Each entry is a plain text file encrypted with GPG. The format is intentionally simple:

first-line-is-always-the-password
key: value
key: value
otpauth://totp/...
any other text
  • Line 1 — the password. Always.
  • key: value lines — metadata (username, url, email, notes, etc.). Any key name works.
  • otpauth:// line — enables TOTP code generation via rpass otp.
  • Everything else — preserved as-is, never parsed.

Note

"The password store does not impose any particular schema or type of organization of your data, as it is simply a flat text file, which can contain arbitrary data." — passwordstore.org

rpass follows this same philosophy. Any layout works.

Path structure

Entries live as .gpg files anywhere under your store directory. You choose the hierarchy:

~/.password-store/
├── email.gpg
├── email/
│   ├── work.gpg
│   └── personal.gpg
└── bank/
    └── checking.gpg

There is no required depth or naming convention. Use whatever makes sense to you.

Recommended structure for rich client integration

Clients like Raycast and Vicinae can display favicons, match entries to websites, and autofill — but only if they can extract a domain name from the entry path.

The recommended structure is:

<category>/<host>/<identifier>.gpg
Part Description Example
<category> Logical group Personal, Work, Finance
<host> Domain without protocol or trailing slash github.com, mail.google.com
<identifier> Username, email, or alias alice, alice@example.com, main

Examples

Personal/github.com/alice
Personal/mail.google.com/alice@gmail.com
Personal/netflix.com/main
Work/jira.company.com/alice
Work/mail.company.com/alice@company.com
Finance/paypal.com/alice
Finance/n26.com/main

Tip

Use the hostname only, without https://, www., or trailing slashes. github.com ✓ — https://github.com/ ✗

Why this matters

When a client sees Personal/github.com/alice, it can:

  1. Extract github.com from the second path segment.
  2. Fetch the favicon (https://github.com/favicon.ico or a favicon service).
  3. Match the entry when you visit github.com in your browser.
  4. Display the site name and icon instead of a raw file path.

Without a hostname in the path, clients fall back to showing the raw path with no icon.

Entry content for autofill

For browser autofill (Raycast, Vicinae, PassForiOS Safari extension) to work correctly, the entry must follow the standard structure:

my-secret-password
username: alice
url: https://github.com

Important

The password must be on the first line. Clients that do autofill read line 1 as the password — always.

Recognized field names for autofill:

Field Accepted names
Username username:, Username:, login:, user:
URL url:, URL:
Email email:
TOTP otpauth://totp/... line

TOTP entries

Add an otpauth:// URI anywhere in the entry (conventionally after the metadata):

my-secret-password
username: alice
url: https://github.com
otpauth://totp/GitHub:alice?secret=JBSWY3DPEHPK3PXP&issuer=GitHub

Generate the code:

rpass otp Personal/github.com/alice
rpass otp Personal/github.com/alice --json

The otpauth:// URI is the same format used by Google Authenticator, Authy, and other TOTP apps. You can scan your existing QR codes and paste the URI directly into the entry.

Migrating an existing store

If you already have a store with a flat or different structure and want to adopt the recommended layout:

rpass mv email/work Personal/mail.company.com/alice
rpass mv github Personal/github.com/alice

rpass mv re-encrypts with the correct recipients for the destination path automatically.

Clone this wiki locally