proton-pass

---
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:
```bash
curl -fsSL https://proton.me/download/pass-cli/install.sh | bash
```

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

### Homebrew (macOS)

```bash
brew install protonpass/tap/pass-cli
```

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

### Verify installation

```bash
pass-cli --version
```

## Authentication

### Web login (recommended)

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

```bash
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):

```bash
pass-cli login --interactive [email protected]
```

#### Environment variables for automation

```bash
# 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

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

### Logout

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

## Vault Management

### List vaults

```bash
pass-cli vault list
pass-cli vault list --output json
```

### Create vault

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

### Update vault

```bash
# 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.

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

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

### Share vault

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:
```json
{
  "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

```bash
# 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

```bash
# 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
```

**Recommendation:** For importing passphrase-protected keys, consider removing the passphrase first since keys will be encrypted in your vault:

```bash
# Create unencrypted copy
cp ~/.ssh/id_ed25519 /tmp/id_ed25519_temp
ssh-keygen -p -f /tmp/id_ed25519_temp -N ""

# Import
pass-cli item create ssh-key import \
  --from-private-key /tmp/id_ed25519_temp \
  --share-id "abc123def" \
  --title "My SSH Key"

# Securely delete temp copy
shred -u /tmp/id_ed25519_temp  # Linux
rm -P /tmp/id_ed25519_temp     # macOS
```

### Create email alias

```bash
# Create alias
pass-cli item alias create --share-id "abc123def" --prefix "newsletter"
pass-cli item alias create --vault-name "Personal" --prefix "shopping"

# With JSON output
pass-cli item alias create --vault-name "Personal" --prefix "temp" --output json
```

### Update item

```bash
# Update single field
pass-cli item update \
  --share-id "abc123def" \
  --item-id "item456" \
  --field "password=newpassword123"

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

# Update multiple fields
pass-cli item update \
  --share-id "abc123def" \
  --item-id "item456" \
  --field "username=newusername" \
  --field "password=newpassword" \
  --field "[email protected]"

# Rename item
pass-cli item update \
  --vault-name "Work" \
  --item-title "Old Title" \
  --field "title=New Title"

# Create/update custom fields
pass-cli item update \
  --share-id "abc123def" \
  --item-id "item456" \
  --field "api_key=sk_live_abc123" \
  --field "environment=production"
```

**Note:** Item update does not support TOTP or time fields. Use another Proton Pass client for those.

### Delete item

⚠️ **Warning:** Permanent deletion.

```bash
pass-cli item delete --share-id "abc123def" --item-id "item456"
```

### Share item

```bash
# Share with viewer access (default)
pass-cli item share --share-id "abc123def" --item-id "item456" [email protected]

# Share with editor access
pass-cli item share --share-id "abc123def" --item-id "item456" [email protected] --role editor
`

... (truncated)