Proton Pass CLI — Practical Tutorial

1. Getting Started

First, log in and verify your session:

pass-cli login        # opens browser for authentication
pass-cli test         # confirm the connection works
pass-cli info         # see account/session details

---

2. Working with Vaults

Vaults are containers for your items. Most commands need you to target a vault by name or ID.

# See all your vaults (also reveals their Share IDs for scripting)
pass-cli vault list

# Create a vault
pass-cli vault create --name "Work"

# Rename a vault
pass-cli vault update --vault-name "Work" --name "Work Passwords"

# Delete a vault (careful — permanent)
pass-cli vault delete --vault-name "Work Passwords"

Tip: --vault-name is convenient for interactive use. In scripts, prefer --share-id since it won't break if you rename a vault.

---

3. Items — The Core Workflow

Listing & Viewing

# List everything in a vault
pass-cli item list "Personal"

# Filter to just logins or notes
pass-cli item list "Personal" --filter-type login
pass-cli item list "Personal" --filter-type note

# View a specific item (shows all fields)
pass-cli item view --vault-name "Personal" --item-title "GitHub"

# Get just one field (great for scripting)
pass-cli item view --vault-name "Personal" --item-title "GitHub" --field password

Creating a Login

pass-cli item create login \
  --vault-name "Personal" \
  --title "GitHub" \
  --username "myuser" \
  --email "me@example.com" \
  --password "s3cr3t" \
  --url "https://github.com"

# Let Proton generate a strong password instead
pass-cli item create login \
  --vault-name "Personal" \
  --title "GitHub" \
  --username "myuser" \
  --generate-password

Creating a Note

pass-cli item create note \
  --vault-name "Personal" \
  --title "Server IPs" \
  --note "prod: 10.0.0.1 | staging: 10.0.0.2"

Updating an Item

Use --field name=value to update specific fields:

pass-cli item update \
  --vault-name "Personal" \
  --item-title "GitHub" \
  --field password=newpassword123

Deleting an Item

Delete requires IDs (run item view --output json to find them):

pass-cli item delete --share-id <SHARE_ID> --item-id <ITEM_ID>

Moving an Item

pass-cli item move \
  --from-vault-name "Personal" \
  --item-title "GitHub" \
  --to-vault-name "Work"

Trash & Recovery

pass-cli item trash   --vault-name "Personal" --item-title "Old Login"
pass-cli item untrash --vault-name "Personal" --item-title "Old Login"

# See what's in the trash
pass-cli item list "Personal" --filter-state trashed

---

4. TOTP (Two-Factor Codes)

# Get a live TOTP code for an item
pass-cli item totp --vault-name "Personal" --item-title "GitHub"

# Generate a code from a raw otpauth:// URI (no vault needed)
pass-cli totp generate

---

5. SSH Keys

# Import an existing key
pass-cli item create ssh-key import \
  --vault-name "Personal" \
  --title "Home Server Key" \
  --from-private-key ~/.ssh/id_ed25519

# Generate a new key pair stored in Proton Pass
pass-cli item create ssh-key generate \
  --vault-name "Personal" \
  --title "New Work Key" \
  --key-type ed25519 \
  --comment "laptop 2025"

# Start the SSH agent so your keys are available to ssh
pass-cli ssh-agent start

# Or run it as a background daemon
pass-cli ssh-agent daemon start
pass-cli ssh-agent daemon status
pass-cli ssh-agent daemon stop

---

6. Secrets in Scripts & CI/CD

This is one of the most powerful features — inject secrets without hardcoding them.

pass-cli run — wrap a command with secrets as env vars

Mark secrets in your script as {{ pass:// }} references, then run:

pass-cli run -- ./deploy.sh
pass-cli run --env-file .env -- python app.py

pass-cli inject — write secrets into a config file

# Template file uses {{ pass://SHARE_ID/ITEM_ID/field }} syntax
pass-cli inject -i config.template.yaml -o config.yaml

---

7. Password Generator (Standalone)

# Random password
pass-cli password generate random --length 24 --symbols true

# Passphrase (easier to remember)
pass-cli password generate passphrase --count 4 --separator hyphens

# Check how strong a password is
pass-cli password score "myP@ssw0rd"

---

8. Personal Access Tokens (Automation)

PATs let scripts authenticate without your main login session.

# Create a token valid for 1 month
pass-cli personal-access-token create --name "CI deploy" --expiration 1m

# Grant it access to a specific vault only
pass-cli personal-access-token access grant \
  --personal-access-token-name "CI deploy" \
  --vault-name "Deploy Secrets" \
  --role viewer

# List tokens, renew, or delete
pass-cli personal-access-token list
pass-cli personal-access-token renew --personal-access-token-name "CI deploy" --expiration 3m
pass-cli personal-access-token delete --personal-access-token-id <ID>

---

9. Sharing

Share a whole vault

pass-cli vault share colleague@example.com \
  --vault-name "Shared Infra" \
  --role editor

Share a single item

pass-cli item share colleague@example.com \
  --share-id <SHARE_ID> \
  --item-id <ITEM_ID> \
  --role viewer

Manage pending invites

pass-cli invite list
pass-cli invite accept
pass-cli invite reject

---

10. Aliases (SimpleLogin)

# Create a new email alias
pass-cli item alias create \
  --vault-name "Personal" \
  --prefix "newsletter-signup"
# Result: newsletter-signup.<suffix>@simplelogin.com

---

Quick Reference

Task	Command
Log in	pass-cli login
List vaults	pass-cli vault list
List items	pass-cli item list <VAULT>
View an item	pass-cli item view --vault-name X --item-title Y
Get one field	... --field password
Get TOTP code	pass-cli item totp --vault-name X --item-title Y
Generate password	pass-cli password generate random --length 24
Run with secrets	pass-cli run -- <command>
Start SSH agent	pass-cli ssh-agent daemon start
Create PAT	pass-cli personal-access-token create --name X --expiration 1m

---

Tips

• Always use --output json when scripting — it gives stable, parseable output.
• Use --share-id instead of --vault-name in scripts to survive vault renames.
• Run any command with --help for full options: pass-cli item create login --help
• Store your PAT in an environment variable (PASS_CLI_TOKEN or similar) for headless environments.