Passclip

TL;DR: A local-first CLI over pass + GPG — inject secrets into processes without shell history or disk writes, auto-clearing clipboard, built-in TOTP, health auditing, encrypted backups, and CSV import from Bitwarden/LastPass/1Password.

pass handles encryption and git. Passclip handles everything around it.

A CLI built on top of pass that adds what it's missing — structured entries, clipboard auto-clear, TOTP, password health checks, CSV import, encrypted backups, and an interactive shell.

Install

# System deps (pass + GPG must be installed separately)
brew install gnupg pass          # macOS
sudo apt install gnupg2 pass     # Ubuntu/Debian

# Passclip
pip install "passclip[all]"

# First-time setup
passclip wizard

Or clone and run directly:

git clone https://github.com/rxb06/Passclip.git
cd Passclip
pip install -e ".[all]"
passclip wizard

See docs/setup.md for GPG key setup, Linux/Arch instructions, and troubleshooting.

Quick start

passclip gmail                    # copy password (fuzzy match)
passclip gmail -u                 # copy username
passclip gmail -o                 # copy OTP code
passclip gmail -s                 # show full entry

No subcommand needed. Type a search term — Passclip finds the entry and copies what you need.

What Passclip adds

pass is solid — one GPG-encrypted file per password, a directory tree as your database, and git for sync. Passclip doesn't replace any of that. It uses pass under the hood for every read and write.

But pass is intentionally minimal, and that minimalism has real gaps in daily use:

What pass gives you:

• Rock-solid GPG encryption
• Git-based version control and sync
• A dead-simple pass insert / pass show interface
• A healthy ecosystem of community extensions

What it doesn't:

• There's no structured format for entries — every user invents their own convention
• No clipboard auto-clear out of the box (and the built-in --clip is inconsistent across platforms)
• No password strength feedback or health audit
• No TOTP without a separate extension (pass-otp)
• Importing from Bitwarden, LastPass, or 1Password means hunting for pass-import
• No interactive shell with tab completion
• No encrypted backup format independent of GPG

What Passclip adds:

Your password store is still a directory of GPG files. pass show, pass insert, pass edit — all still work. Passclip reads and writes through pass, not around it. No lock-in.

How it compares

Passclip is not:

• A cloud password manager (no account, no sync server)
• A replacement for pass/GPG storage (it uses pass under the hood for every read and write)
• A secrets server like HashiCorp Vault (it's a local CLI tool)
• Windows-compatible (pass and GPG tooling assume a Unix environment — macOS and Linux only)

It is: a secure local interface for using secrets stored in pass.

What can it do?

Secure secret injection — the differentiator:

passclip run aws/prod -- aws s3 ls    # inject secrets as env vars
passclip run db/prod -- psql          # secrets never hit disk or shell history

# verify: nothing leaks
env | grep PASS_                      # empty after process exits

Quick copy — the daily driver:

passclip gmail                        # fuzzy match → copy password
passclip gmail -u                     # copy username
passclip gmail -o                     # copy OTP code
passclip gmail -s                     # show full entry

Full commands:

passclip get email/gmail --clip       # copy to clipboard, auto-clears in 45s
passclip insert web/github            # add entry (guided prompts)
passclip browse                       # interactive picker → copy by default
passclip otp --add web/github         # add OTP secret to an entry

Housekeeping:

passclip health                       # password strength + duplicate report
passclip sync                         # git pull + push
passclip archive web/old-site         # stash it, don't delete it
passclip export-vault ~/backup.vault  # AES-256 encrypted backup

Migration:

passclip import bitwarden_export.csv  # migrate from another manager
passclip import export.csv --dry-run  # preview before committing

Interactive shell — launch with passclip. Single-letter shortcuts: c gmail (password), u gmail (username), o gmail (OTP).

All commands

(shell only) commands are available inside the interactive shell (passclip), not as direct CLI subcommands.

Pre-commit hook

Passclip uses Credactor to scan for hardcoded credentials before every commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/Credactor
    rev: v2.2.2
    hooks:
      - id: credactor

pip install pre-commit
pre-commit install

See docs/integration.md for CI setup and more.

How entries are stored

Passclip uses the same format as pass — GPG-encrypted files, one per entry:

MyS3cr3tP@ssw0rd
username: john@example.com
url: https://github.com
notes: work account

First line is always the password. Everything else is optional key: value metadata. Compatible with pass-import and most pass extensions.

Security

Properties:

• Secrets are not written to disk during normal operation (exception: pre-delete backups are plaintext — see below)
• Never exposed in shell history — passed as env vars or clipboard, not CLI args
• run injects secrets as env vars into child processes — they are visible in /proc/<pid>/environ on Linux for the lifetime of that process
• Clipboard auto-clears after configurable timeout (constant-time comparison)
• All subprocess calls use list arguments — no shell=True anywhere
• Vault encryption authenticates header metadata (AAD) — tampering is detected
• Tar extraction rejects symlinks, hardlinks, and path traversal

Controls:

• Entry name validation blocks .., shell metacharacters, control characters, and excessive depth
• Atomic vault writes — no partial files on disk-full
• Pre-delete backups saved to ~/.config/passclip/backups/ with 0600 permissions
• AES-256-GCM with PBKDF2-SHA256 at 600,000 iterations

Full threat model: SECURITY.md

Documentation

License

Licensed under the GNU General Public License v3.0.

Passclip is a personal open-source project. It is not audited by a third party. See docs/disclaimer.md for details.