--- name: proton-pass description: Manage Proton Pass vaults, items (logins, SSH keys, aliases, notes), passwords, SSH agent integration, and secret injection into applications. Use when working with Proton Pass for password management, SSH key storage, secret injection (run commands with secrets, inject into templates), environment variable injection, or generating secure passwords. Supports vault/item CRUD, sharing, member management, SSH agent operations, TOTP generation, secret references (pass://vault/item/field), template injection, and command execution with secrets. ---

Proton Pass CLI

Comprehensive password and secret management via the Proton Pass CLI. Manage vaults, items, SSH keys, share credentials, inject secrets, and integrate with SSH workflows.

Installation

Quick install

macOS/Linux:

curl -fsSL https://proton.me/download/pass-cli/install.sh | bash

Windows:

Invoke-WebRequest -Uri https://proton.me/download/pass-cli/install.ps1 -OutFile install.ps1; .\install.ps1

Homebrew (macOS)

brew install protonpass/tap/pass-cli

Note: Package manager installations (Homebrew, etc.) do not support pass-cli update command or track switching.

Verify installation

pass-cli --version

Authentication

Web login (recommended)

Default authentication method supporting all login flows (SSO, U2F):

pass-cli login
# Open the URL displayed in your browser and complete authentication

Interactive login

Terminal-based authentication (supports password + TOTP, but not SSO or U2F):

pass-cli login --interactive [email protected]

Environment variables for automation

# Credentials as plain text (less secure)
export PROTON_PASS_PASSWORD='your-password'
export PROTON_PASS_TOTP='123456'
export PROTON_PASS_EXTRA_PASSWORD='your-extra-password'

# Or from files (more secure)
export PROTON_PASS_PASSWORD_FILE='/secure/password.txt'
export PROTON_PASS_TOTP_FILE='/secure/totp.txt'
export PROTON_PASS_EXTRA_PASSWORD_FILE='/secure/extra-password.txt'

pass-cli login --interactive [email protected]

Verify session

pass-cli info          # Show session info
pass-cli test          # Test connection

Logout

pass-cli logout        # Normal logout
pass-cli logout --force  # Force local cleanup if remote fails

Vault Management

List vaults

pass-cli vault list
pass-cli vault list --output json

Create vault

pass-cli vault create --name "Vault Name"

Update vault

# By share ID
pass-cli vault update --share-id "abc123def" --name "New Name"

# By name
pass-cli vault update --vault-name "Old Name" --name "New Name"

Delete vault

⚠️ Warning: Permanently deletes vault and all items.

# By share ID
pass-cli vault delete --share-id "abc123def"

# By name
pass-cli vault delete --vault-name "Old Vault"

Share vault

# Share with viewer access (default)
pass-cli vault share --share-id "abc123def" [email protected]

# Share with specific role
pass-cli vault share --vault-name "Team Vault" [email protected] --role editor

# Roles: viewer, editor, manager

Manage vault members

# List members
pass-cli vault member list --share-id "abc123def"
pass-cli vault member list --vault-name "Team Vault" --output json

# Update member role
pass-cli vault member update --share-id "abc123def" --member-share-id "member123" --role editor

# Remove member
pass-cli vault member remove --share-id "abc123def" --member-share-id "member123"

Transfer vault ownership

pass-cli vault transfer --share-id "abc123def" "member_share_id_xyz"
pass-cli vault transfer --vault-name "My Vault" "member_share_id_xyz"

Item Management

List items

# List from specific vault
pass-cli item list "Vault Name"
pass-cli item list --share-id "abc123def"

# List with default vault (if configured)
pass-cli item list

View item

# By IDs
pass-cli item view --share-id "abc123def" --item-id "item456"

# By names
pass-cli item view --vault-name "MyVault" --item-title "MyItem"

# Using Pass URI
pass-cli item view "pass://abc123def/item456"
pass-cli item view "pass://MyVault/MyItem"

# View specific field
pass-cli item view "pass://abc123def/item456/password"
pass-cli item view --share-id "abc123def" --item-id "item456" --field "username"

# Output format
pass-cli item view --share-id "abc123def" --item-id "item456" --output json

Create login item

# Basic login
pass-cli item create login \
  --share-id "abc123def" \
  --title "GitHub Account" \
  --username "myuser" \
  --password "mypassword" \
  --url "https://github.com"

# With vault name
pass-cli item create login \
  --vault-name "Personal" \
  --title "Account" \
  --username "user" \
  --email "[email protected]" \
  --url "https://example.com"

# With generated password
pass-cli item create login \
  --share-id "abc123def" \
  --title "New Account" \
  --username "myuser" \
  --generate-password \
  --url "https://example.com"

# Custom password generation: "length,uppercase,symbols"
pass-cli item create login \
  --vault-name "Work" \
  --title "Secure Account" \
  --username "myuser" \
  --generate-password="20,true,true" \
  --url "https://example.com"

# Generate passphrase
pass-cli item create login \
  --share-id "abc123def" \
  --title "Account" \
  --username "user" \
  --generate-passphrase="5" \
  --url "https://example.com"

Login template

# Get template structure
pass-cli item create login --get-template > template.json

# Create from template
pass-cli item create login --from-template template.json --share-id "abc123def"

# Create from stdin
echo '{"title":"Test","username":"user","password":"pass","urls":["https://test.com"]}' | \
  pass-cli item create login --share-id "abc123def" --from-template -

Template format:

{
  "title": "Item Title",
  "username": "optional_username",
  "email": "[email protected]",
  "password": "optional_password",
  "urls": ["https://example.com", "https://app.example.com"]
}

Create SSH key items

Generate new SSH key

# Generate Ed25519 key (recommended)
pass-cli item create ssh-key generate \
  --share-id "abc123def" \
  --title "GitHub Deploy Key"

# Using vault name
pass-cli item create ssh-key generate \
  --vault-name "Development Keys" \
  --title "GitHub Deploy Key"

# Generate RSA 4096 key with comment
pass-cli item create ssh-key generate \
  --share-id "abc123def" \
  --title "Production Server" \
  --key-type rsa4096 \
  --comment "prod-server-deploy"

# Key types: ed25519 (default), rsa2048, rsa4096

# With passphrase protection
pass-cli item create ssh-key generate \
  --share-id "abc123def" \
  --title "Secure Key" \
  --password

# Passphrase from environment
PROTON_PASS_SSH_KEY_PASSWORD="my-passphrase" \
  pass-cli item create ssh-key generate \
  --share-id "abc123def" \
  --title "Automated Key" \
  --password

Import existing SSH key

# Import unencrypted key
pass-cli item create ssh-key import \
  --from-private-key ~/.ssh/id_ed25519 \
  --share-id "abc123def" \
  --title "My SSH Key"

# Import with vault name
pass-cli item create ssh-key import \
  --from-private-key ~/.ssh/id_rsa \
  --vault-name "Personal Keys" \
  --title "Old RSA Key"

# Import passphrase-protected key (will prompt)
pass-cli item create ssh-key import \
  --from-private-key ~/.ssh/id_ed25519 \
  --share-id "abc123def" \
  --title "Protected Key" \
  --password

# Passphrase from environment
PROTON_PASS_SSH_KEY_PASSWORD="my-key-passphrase" \
  pass-cli item create ssh-key import \
  --from-private-key ~/.ssh/id_ed25519 \
  --share-id "abc123def" \
  --title "Automated Import" \
  --password

...