Proton Pass CLI

https://protonpass.github.io/pass-cli
Admin
Proton Pass CLI is a command-line interface for managing Proton Pass vaults, items, and secrets with...
Tokens:56,216
Snippets:668
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Daemon start options

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Examples of starting the daemon with various configuration flags.

```bash
pass-cli ssh-agent daemon start --vault-name MySshKeysVault
pass-cli ssh-agent daemon start --share-id MY_SHARE_ID
pass-cli ssh-agent daemon start --refresh-interval 7200
pass-cli ssh-agent daemon start --create-new-identities MySshKeysVault
pass-cli ssh-agent daemon start --socket-path /tmp/my-agent.sock
```

--------------------------------

### Basic update example

Source: https://protonpass.github.io/pass-cli/commands/update

Shows the update command with its expected output, including the confirmation prompt and installation messages.

```bash
pass-cli update
# Update pass-cli v1.0.0 → v1.1.0? [Y/n]
# Downloading pass-cli v1.1.0...
# Installing...
# Updated to v1.1.0.

```

--------------------------------

### Example workflow for auto-creation

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Shows a complete workflow: start the agent with auto-creation, export the socket path, add a new SSH key, and the key is automatically stored.

```bash
# Start the agent with auto-creation enabled
pass-cli ssh-agent start --create-new-identities MySshKeysVault

# In another terminal, export the socket path
export SSH_AUTH_SOCK=$HOME/.ssh/proton-pass-agent.sock

# Add a new SSH key
ssh-add ~/.ssh/my_new_key

# The key is now automatically stored in your Proton Pass vault!

```

--------------------------------

### SSH agent startup output

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Example output after starting the SSH agent, showing the socket path and refresh interval.

```text
SSH agent started successfully!
To use this agent, run:
  export SSH_AUTH_SOCK=/Users/youruser/.ssh/proton-pass-agent.sock

Keys will refresh automatically every 3600 seconds.

Press Ctrl+C to stop the agent.

```

--------------------------------

### Examples of user info command

Source: https://protonpass.github.io/pass-cli/commands/user

Examples showing how to display user information in human-readable and JSON formats.

```bash
# Display user information in human-readable format
pass-cli user info

# Display user information in JSON format
pass-cli user info --output json
```

--------------------------------

### invite accept example

Source: https://protonpass.github.io/pass-cli/commands/invite

Example of accepting an invitation with a specific token.

```bash
# Accept an invitation
pass-cli invite accept --invite-token "abc123def456"

```

--------------------------------

### Managing invitation workflow example

Source: https://protonpass.github.io/pass-cli/commands/invite

Example workflow showing how to check for pending invitations and accept a specific one.

```bash
# Check for new invitations
echo "=== Pending Invitations ==="
pass-cli invite list

# Accept specific invitations
pass-cli invite accept --invite-token "vault_invite_123"

```

--------------------------------

### Manual installation - versions listing URL

Source: https://protonpass.github.io/pass-cli/get-started/installation

URL to download the versions listing file for manual installation. Use it to find the appropriate binary for your platform.

```text
https://proton.me/download/pass-cli/versions.json

```

--------------------------------

### CI/CD integration example

Source: https://protonpass.github.io/pass-cli/commands/contents/run

Example of using pass-cli run in a CI/CD deployment script to load production secrets.

```bash
#!/bin/bash
# CI/CD deployment script

# Load production secrets
pass-cli run \
  --env-file .env.production \
  -- ./deploy.sh
```

--------------------------------

### Verify installation on macOS/Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Checks that the CLI is installed correctly by printing the version number. If you get a 'command not found' error, ensure the installation directory is in your PATH.

```bash
pass-cli --version

```

--------------------------------

### Update without confirmation example

Source: https://protonpass.github.io/pass-cli/commands/update

Shows the --yes flag in action, skipping the confirmation prompt and directly downloading and installing the update.

```bash
pass-cli update --yes
# Downloading pass-cli v1.1.0...
# Installing...
# Updated to v1.1.0.

```

--------------------------------

### invite list examples

Source: https://protonpass.github.io/pass-cli/commands/invite

Examples of listing pending invitations in human-readable and JSON formats.

```bash
# List pending invitations
pass-cli invite list

# List invitations in JSON format
pass-cli invite list --output json

```

--------------------------------

### Install Proton Pass CLI on Windows

Source: https://protonpass.github.io/pass-cli

Use PowerShell to download and execute the installation script on Windows systems.

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

--------------------------------

### List shares examples

Source: https://protonpass.github.io/pass-cli/commands/share

Examples of listing shares in human-readable and JSON formats.

```bash
# List all shares in human-readable format
pass-cli share list

# List shares in JSON format for scripting
pass-cli share list --output json
```

--------------------------------

### Complete example

Source: https://protonpass.github.io/pass-cli/commands/contents/inject

A full workflow showing the template file content and the command to process it.

```yaml
# config.yaml.template
database:
  host: localhost
  port: 5432
  username: {{ pass://Production/Database/username }}
  password: {{ pass://Production/Database/password }}

api:
  key: {{ pass://Work/API Keys/api_key }}
  secret: {{ pass://Work/API Keys/secret }}

# This comment with pass://fake/uri is ignored
# Only {{ }} wrapped references are processed
```

```bash
pass-cli inject --in-file config.yaml.template --out-file config.yaml
```

--------------------------------

### Quick install on macOS and Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Proton Pass CLI using the official installation script. The script detects OS and architecture, downloads the latest stable release, verifies binary integrity, installs to a PATH directory, and checks dependencies.

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

```

--------------------------------

### pat list - example output

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example of running pat list and its output, showing token IDs and expiration dates.

```bash
pass-cli pat list
# - [abc123]: deploy-bot (expires: 2025-06-01)
# - [def456]: staging-reader (expires: 2025-07-15)

```

--------------------------------

### Daemon startup output

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Example output showing the PID, PID file location, and socket path.

```text
Daemon started (PID: 12345)
PID file: /home/youruser/.ssh/proton-pass-agent.pid
Logs: discarded (use --log-file to capture them)

To connect to the agent, set SSH_AUTH_SOCK:
  export SSH_AUTH_SOCK=/home/youruser/.ssh/proton-pass-agent.sock
```

--------------------------------

### pass-cli item list examples

Source: https://protonpass.github.io/pass-cli/commands/item

Examples of listing items with default settings, by vault name (positional or --vault-name), by share ID, and with output format overrides.

```bash
# List items using default vault and format (requires settings configured)
pass-cli item list

# List items in a specific vault by name (positional)
pass-cli item list "Personal Vault"

# List items in a specific vault by name (using --vault-name flag)
pass-cli item list --vault-name "Personal Vault"

# List items in a specific vault by share ID
pass-cli item list --share-id "abc123def"

# List items in JSON format
pass-cli item list --output json

# Using default vault but override format
pass-cli item list --output human

```

--------------------------------

### Complex execution example

Source: https://protonpass.github.io/pass-cli/commands/contents/run

A bash script example setting environment variables and running a node server with multiple .env files.

```bash
#!/bin/bash
# Set some environment variables
export NODE_ENV=production
export LOG_LEVEL=info

# Run with secrets from .env files
pass-cli run \
  --env-file .env.production \
  --env-file .env.secrets \
  -- node server.js --port 3000
```

--------------------------------

### pass-cli item create login examples

Source: https://protonpass.github.io/pass-cli/commands/item

Examples of creating login items with various options: default vault, share ID, vault name, generated passwords, templates, and stdin input.

```bash
# Create using default vault (if configured)
pass-cli item create login \
  --title "GitHub Account" \
  --username "myuser" \
  --password "mypassword" \
  --url "https://github.com"

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

# Create a basic login item using vault name
pass-cli item create login \
  --vault-name "Personal" \
  --title "GitHub Account" \
  --username "myuser" \
  --password "mypassword" \
  --url "https://github.com"

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

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

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

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

# Create from template file using vault name
pass-cli item create login --from-template template.json --vault-name "Personal"

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

```

--------------------------------

### Item update output example

Source: https://protonpass.github.io/pass-cli/commands/item

Example of the feedback provided by the CLI after a successful field update.

```text
Updated field: password
Updated field: username
Created new custom field: api_key
Item updated successfully: 2 field(s) updated, 1 custom field(s) created
```

--------------------------------

### Verify installation on Windows

Source: https://protonpass.github.io/pass-cli/get-started/installation

Checks that the CLI is installed correctly on Windows by printing the version number.

```powershell
pass-cli.exe --version

```

--------------------------------

### Example: pass-cli pat create with output

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example command to create a token named 'deploy-bot' with a 3-month expiration. The output is ready to use as an environment variable.

```bash
pass-cli pat create --name "deploy-bot" --expiration 3m
# PROTON_PASS_PERSONAL_ACCESS_TOKEN=pst_xxxx...xxxx::TOKENKEY
```

--------------------------------

### Import SSH Key Examples

Source: https://protonpass.github.io/pass-cli/commands/item

Various examples for importing SSH keys, including using vault names, share IDs, and handling passphrases via prompts, environment variables, or files.

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

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

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

```bash
# Import with passphrase from environment variable
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
```

```bash
# Import with passphrase from file
PROTON_PASS_SSH_KEY_PASSWORD_FILE="/secure/passphrase.txt" \
  pass-cli item create ssh-key import \
  --from-private-key ~/.ssh/id_ed25519 \
  --share-id "abc123def" \
  --title "Key with File Passphrase" \
  --password
```

--------------------------------

### invite reject example

Source: https://protonpass.github.io/pass-cli/commands/invite

Example of rejecting an invitation with a specific token.

```bash
# Reject an invitation
pass-cli invite reject --invite-token "abc123def456"

```

--------------------------------

### Install Fish completions on macOS/Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Fish completion script for Proton Pass CLI on macOS/Linux.

```bash
mkdir -p ~/.config/fish/completions
pass-cli completions fish > ~/.config/fish/completions/pass-cli.fish

```

--------------------------------

### Start an SSH agent with eval

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Common way to start an SSH agent if one is not already running on your system.

```bash
eval $(ssh-agent)

```

--------------------------------

### Alias create examples

Source: https://protonpass.github.io/pass-cli/commands/item

Examples of creating email aliases using default vaults, share IDs, vault names, and JSON output.

```bash
# Create alias using default vault (if configured)
pass-cli item alias create --prefix "shopping"

# Create alias using share ID
pass-cli item alias create --share-id "abc123def" --prefix "newsletter"

# Create alias using vault name
pass-cli item alias create --vault-name "Personal" --prefix "work-signup"

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

--------------------------------

### Install beta channel on Windows

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Proton Pass CLI from the beta channel on Windows by setting the PROTON_PASS_CLI_INSTALL_CHANNEL environment variable.

```powershell
Invoke-WebRequest -Uri https://proton.me/download/pass-cli/install.ps1 -OutFile install.ps1
$env:PROTON_PASS_CLI_INSTALL_CHANNEL="beta"; .\install.ps1

```

--------------------------------

### Complete ssh-copy-id command example

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

A full example of the command using specific port and user credentials.

```bash
ssh-copy-id -o PreferredAuthentications=password -o PubkeyAuthentication=no -p 2222 user@server
```

--------------------------------

### Examples for password generate passphrase

Source: https://protonpass.github.io/pass-cli/commands/password

Examples for generating passphrases. The first uses default settings, the second generates a 5-word passphrase, the third uses a custom separator, and the fourth includes numbers and capitalization.

```bash
# Generate with default settings
pass-cli password generate passphrase

# Generate a 5-word passphrase
pass-cli password generate passphrase --count 5

# Generate with custom separator
pass-cli password generate passphrase --count 4 --separator hyphens

# Generate with numbers and capitalization
pass-cli password generate passphrase --count 4 --capitalize true --numbers true

```

--------------------------------

### Install beta channel on macOS and Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Proton Pass CLI from the beta channel by setting the PROTON_PASS_CLI_INSTALL_CHANNEL environment variable. Includes a one-liner alternative.

```bash
export PROTON_PASS_CLI_INSTALL_CHANNEL=beta
curl -fsSL https://proton.me/download/pass-cli/install.sh | bash

# Or as a one-liner
curl -fsSL https://proton.me/download/pass-cli/install.sh | PROTON_PASS_CLI_INSTALL_CHANNEL=beta bash

```

--------------------------------

### pat access list-access example with output

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example of using `pat access list-access` with `--pat-name` to show access grants for a token named 'deploy-bot'. The output lists each vault and item with its role and expiration time.

```bash
pass-cli pat access list-access --pat-name "deploy-bot"
# Personal access token access grants:
#
# - [share_abc] Production | Type=Vault | Role=Viewer | Expires: 2025-06-01 00:00 (UTC)
# - [share_abc] DB password | Type=Item | Role=Viewer | Expires: 2025-06-01 00:00 (UTC)

```

--------------------------------

### TOTP authentication methods

Source: https://protonpass.github.io/pass-cli/commands/login

Examples for providing the TOTP token via interactive prompt, environment variable, or file.

```bash
pass-cli login --interactive user@proton.me
# Enter password:
# Enter TOTP:
```

```bash
export PROTON_PASS_TOTP='123456'
pass-cli login --interactive user@proton.me
```

```bash
echo '123456' > /secure/totp.txt
export PROTON_PASS_TOTP_FILE='/secure/totp.txt'
pass-cli login --interactive user@proton.me
```

--------------------------------

### Start SSH agent with debug logs (macOS/Linux)

Source: https://protonpass.github.io/pass-cli/help/troubleshoot

Start the SSH agent with debug logging on macOS or Linux.

```bash
PASS_LOG_LEVEL=debug pass-cli ssh-agent start --vault-name YOUR_VAULT_NAME
```

--------------------------------

### Switch to beta track

Source: https://protonpass.github.io/pass-cli/commands/update

Gets early access to new features by switching to the beta track. After switching, run the update command again to get the latest beta version.

```bash
pass-cli update --set-track beta

```

```bash
pass-cli update

```

--------------------------------

### TOTP Secret Reference Examples

Source: https://protonpass.github.io/pass-cli/commands/contents/secret-references

Examples showing how to resolve TOTP fields to either the current code or the raw otpauth URI.

```text
# Resolve to the current TOTP code (default)
pass://Work/GitHub/totp
pass://Work/GitHub/totp?totp=code

# Resolve to the raw otpauth:// URI
pass://Work/GitHub/totp?totp=uri
```

--------------------------------

### Transfer vault ownership examples

Source: https://protonpass.github.io/pass-cli/commands/vault

Examples showing how to transfer vault ownership using either a share ID or a vault name.

```bash
# Transfer vault ownership by Share ID
pass-cli vault transfer --share-id "abc123def" "member_share_id_xyz"

# Transfer vault ownership by name
pass-cli vault transfer --vault-name "My Vault" "member_share_id_xyz"
```

--------------------------------

### Start daemon with log file

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Captures daemon output to a specified log file for troubleshooting.

```bash
pass-cli ssh-agent daemon start --log-file ~/.ssh/proton-pass-agent.log
```

--------------------------------

### Basic logout example

Source: https://protonpass.github.io/pass-cli/commands/logout

Performs a basic logout and displays the success message.

```bash
pass-cli logout
# Successfully logged out

```

--------------------------------

### Generate SSH key examples

Source: https://protonpass.github.io/pass-cli/commands/item

Examples of generating SSH keys with various options: default vault, share ID, vault name, RSA 4096 with comment, passphrase protection, and passphrase from environment variable.

```bash
# Generate using default vault (if configured)
pass-cli item create ssh-key generate \
  --title "GitHub Deploy Key"

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

# Generate an Ed25519 key using vault name
pass-cli item create ssh-key generate \
  --vault-name "Development Keys" \
  --title "GitHub Deploy Key"

# Generate an 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"

# Generate a passphrase-protected key
pass-cli item create ssh-key generate \
  --share-id "abc123def" \
  --title "Secure Key" \
  --password

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

```

--------------------------------

### agent create example with multiple vaults

Source: https://protonpass.github.io/pass-cli/commands/agent

Example of creating an agent with a 3-month expiration and access to two vaults. The output is JSON containing the token and a usage hint; the token is shown only once.

```bash
pass-cli agent create my-agent --expiration 3m --vault "Production" --vault "Staging"
# {
#   "token": "PROTON_PASS_PERSONAL_ACCESS_TOKEN=pst_xxxx...xxxx::TOKENKEY",
#   "instruction": "..."
# }
```

--------------------------------

### Examples for password generate random

Source: https://protonpass.github.io/pass-cli/commands/password

Examples for generating random passwords. The first uses default settings, the second creates a 20-character password with all character types, and the third creates a 16-character password without symbols.

```bash
# Generate with default settings
pass-cli password generate random

# Generate a 20-character password with all character types
pass-cli password generate random --length 20 --numbers true --uppercase true --symbols true

# Generate a simple password without symbols
pass-cli password generate random --length 16 --symbols false

```

--------------------------------

### Basic information display output

Source: https://protonpass.github.io/pass-cli/commands/info

Example output showing the fields returned by the info command.

```text
pass-cli info
- Release track: stable
- ID: YOUR_USER_ID
- Username: your-username
- Email: youruser@proton.me
- Session has lock: no
```

--------------------------------

### Daemon status output

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Example output when the daemon is running.

```text
Status:   running
PID:      12345
Socket:   /home/youruser/.ssh/proton-pass-agent.sock

To connect to the agent, set SSH_AUTH_SOCK:
  export SSH_AUTH_SOCK=/home/youruser/.ssh/proton-pass-agent.sock

PID file: /home/youruser/.ssh/proton-pass-agent.pid
```

--------------------------------

### Daemon status with logs

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Example output including the last 10 lines of the log file.

```text
Status:   running
PID:      12345
Socket:   /home/youruser/.ssh/proton-pass-agent.sock

To connect to the agent, set SSH_AUTH_SOCK:
  export SSH_AUTH_SOCK=/home/youruser/.ssh/proton-pass-agent.sock

PID file: /home/youruser/.ssh/proton-pass-agent.pid
Log file: /home/youruser/.ssh/proton-pass-agent.log

Last 3 log line(s):
  Retrieving SSH keys from Proton Pass...
  Loaded 4 SSH key(s) successfully
  Listening on /home/youruser/.ssh/proton-pass-agent.sock
```

--------------------------------

### Example of unlocking the session

Source: https://protonpass.github.io/pass-cli/commands/session

Unlocking the session by providing the lock code.

```bash
pass-cli session unlock
# Enter lock code:
# Session unlocked successfully
```

--------------------------------

### Switch to beta track example

Source: https://protonpass.github.io/pass-cli/commands/update

Demonstrates switching to the beta track and then updating to the latest beta version, with the confirmation prompt shown.

```bash
# Set the track
pass-cli update --set-track beta
# Update track set to beta

# Update to latest beta version
pass-cli update
# Update pass-cli v1.0.0 → v1.1.0-beta.1? [Y/n]

```

--------------------------------

### Check current version and track example

Source: https://protonpass.github.io/pass-cli/commands/update

Shows the info command output when on the beta track, including the release track and account details.

```bash
pass-cli info
# - Release track: beta
# - ID: YOUR_USER_ID
# - Username: your-username
# - Email: youruser@proton.me

```

--------------------------------

### Custom installation directory on Windows

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Proton Pass CLI to a custom directory on Windows by setting the PROTON_PASS_CLI_INSTALL_DIR environment variable before running the installation script.

```powershell
Invoke-WebRequest -Uri https://proton.me/download/pass-cli/install.ps1 -OutFile install.ps1
$env:PROTON_PASS_CLI_INSTALL_DIR="C:\custom\path"; .\install.ps1

```

--------------------------------

### Return to stable releases example

Source: https://protonpass.github.io/pass-cli/commands/update

Shows switching back to the stable track and then updating to the latest stable version, with the confirmation prompt.

```bash
# Switch back to stable
pass-cli update --set-track stable
# Update track set to stable

# Update to latest stable version
pass-cli update
# Update pass-cli v1.1.0-beta.1 → v1.0.5? [Y/n]

```

--------------------------------

### Custom installation directory on macOS and Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Proton Pass CLI to a custom directory by setting the PROTON_PASS_CLI_INSTALL_DIR environment variable before running the installation script.

```bash
export PROTON_PASS_CLI_INSTALL_DIR=/custom/path
curl -fsSL https://proton.me/download/pass-cli/install.sh | bash

```

--------------------------------

### pat delete - example

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example of deleting a token with ID abc123.

```bash
pass-cli pat delete --personal-access-token-id abc123

```

--------------------------------

### Password authentication methods

Source: https://protonpass.github.io/pass-cli/commands/login

Examples for providing the account password via interactive prompt, environment variable, or file.

```bash
pass-cli login --interactive user@proton.me
# You will be prompted: Enter password:
```

```bash
export PROTON_PASS_PASSWORD='your-password'
pass-cli login --interactive user@proton.me
```

```bash
echo 'your-password' > /secure/password.txt
export PROTON_PASS_PASSWORD_FILE='/secure/password.txt'
pass-cli login --interactive user@proton.me
```

--------------------------------

### Install Bash completions on macOS/Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Bash completion script for Proton Pass CLI on macOS/Linux.

```bash
mkdir -p ~/.local/share/bash-completion/completions
pass-cli completions bash > ~/.local/share/bash-completion/completions/pass-cli

```

--------------------------------

### Start SSH agent with debug logs (Windows)

Source: https://protonpass.github.io/pass-cli/help/troubleshoot

Start the SSH agent with debug logging on Windows.

```powershell
$env:PASS_LOG_LEVEL="debug"; pass-cli ssh-agent start --vault-name YOUR_VAULT_NAME
```

--------------------------------

### Examples of creating a session lock

Source: https://protonpass.github.io/pass-cli/commands/session

Demonstrates creating a lock with the default 5-minute timeout and a custom 10-minute timeout.

```bash
# Lock with the default 5-minute timeout
pass-cli session create-lock
# Enter lock code:
# Session locked successfully
# Lock with a custom 10-minute timeout
pass-cli session create-lock --idle-timeout 600
# Enter lock code:
# Session locked successfully
```

--------------------------------

### Second password authentication methods

Source: https://protonpass.github.io/pass-cli/commands/login

Examples for providing the second password via interactive prompt, environment variable, or file.

```bash
pass-cli login --interactive user@proton.me
# Enter password:
# (Optional) Enter TOTP:
# Enter your second password to unlock your data:
```

```bash
export PROTON_PASS_SECOND_PASSWORD='your-second-password'
pass-cli login --interactive user@proton.me
```

```bash
echo 'your-second-password' > /secure/second-password.txt
export PROTON_PASS_SECOND_PASSWORD_FILE='/secure/second-password.txt'
pass-cli login --interactive user@proton.me
```

--------------------------------

### View item examples

Source: https://protonpass.github.io/pass-cli/commands/contents/view

Various ways to view items using IDs, vault names, URIs, specific fields, and different output formats.

```bash
# View item by IDs
pass-cli item view --share-id "abc123def" --item-id "item456"

# View item by vault name and item title
pass-cli item view --vault-name "MyVault" --item-title "MyItem"

# View item using Pass URI
pass-cli item view "pass://abc123def/item456"

# View specific field using URI
pass-cli item view "pass://abc123def/item456/password"

# View specific field using options
pass-cli item view --share-id "abc123def" --item-id "item456" --field "username"

# View item in JSON format
pass-cli item view --share-id "abc123def" --item-id "item456" --output json

# Using the 'get' alias
pass-cli item get --share-id "abc123def" --item-id "item456"

# Using the 'read' alias
pass-cli item read --vault-name "MyVault" --item-title "MyItem"
```

--------------------------------

### SSH key loading summary output

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Example output after loading SSH keys, showing counts of successfully loaded, already loaded, and total keys.

```text
SSH Key Loading Summary:
  Successfully loaded: 0
  Already loaded (skipped): 3
  Total keys: 3

All keys were already present in the system SSH agent.
You can verify with: ssh-add -l

```

--------------------------------

### Install Proton Pass CLI on Linux/macOS

Source: https://protonpass.github.io/pass-cli

Use the provided curl command to download and execute the installation script on Unix-based systems.

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

--------------------------------

### Install Proton Pass CLI in GitHub Actions

Source: https://protonpass.github.io/pass-cli/developer-resources

Installs pass-cli into the workflow PATH and authenticates using a personal access token.

```yaml
- uses: protonpass/install-cli-action@v1
  with:
    version: '2.1.4'
  env:
    PROTON_PASS_PERSONAL_ACCESS_TOKEN: ${{ secrets.PROTON_PAT }}
```

--------------------------------

### TOTP generation examples

Source: https://protonpass.github.io/pass-cli/commands/item

Examples of generating TOTP codes using item titles, pass URIs, and different output formats.

```bash
# Generate TOTP using default vault and format (if configured)
pass-cli item totp --item-title "WithTOTPs"

# Generate all TOTPs on a given item (Readable format)
pass-cli item totp "pass://TOTP export/WithTOTPs"
# TOTP 1: 343325
# TOTP 2: 068223
# totp: 639378

# Generate all TOTPs on a given item (JSON format)
pass-cli item totp "pass://TOTP export/WithTOTPs" --output=json
# {
#   "TOTP 2": "622653",
#   "TOTP 1": "119533",
#   "totp": "152470",
# }

# Generate the TOTP for a given item and field
pass-cli item totp "pass://TOTP export/WithTOTPs/TOTP 1"
# TOTP 1: 343325

# Generate the TOTP for a given item and field and get only the value
pass-cli item totp "pass://TOTP export/WithTOTPs/TOTP 1" --output=json | jq -r '."TOTP 1"'
# 474540
```

--------------------------------

### Typical workflow: create, grant, and use a personal access token

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Full setup from scratch: create a token valid for 3 months, grant read-only access to a vault, then store the token in CI secrets and use it to log in. The token value is shown as `pst_xxxx...xxxx::TOKENKEY`.

```bash
# 1. Create a token valid for 3 months
pass-cli pat create --name "ci-runner" --expiration 3m
# PROTON_PASS_PERSONAL_ACCESS_TOKEN=pst_xxxx...xxxx::TOKENKEY

# 2. Grant it read-only access to the vault it needs
pass-cli pat access grant --pat-name "ci-runner" --vault-name "CI Secrets" --role viewer

# 3. Store the token in your CI secrets and use it to log in
PROTON_PASS_PERSONAL_ACCESS_TOKEN=pst_xxxx...xxxx::TOKENKEY pass-cli login

```

--------------------------------

### Use filesystem key storage for headless/SSH

Source: https://protonpass.github.io/pass-cli/help/troubleshoot

Log out, set the key provider to filesystem, and log in again for environments where neither keyring backend is accessible.

```bash
pass-cli logout --force
export PROTON_PASS_KEY_PROVIDER=fs
pass-cli login
```

--------------------------------

### View all settings

Source: https://protonpass.github.io/pass-cli/commands/settings

Displays all configured settings and their current values, including defaults for unset items.

```bash
pass-cli settings view
```

```bash
# View all settings
pass-cli settings view
```

--------------------------------

### Revoke access example

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example that revokes a token's access to a vault using the token name and the placeholder share ID.

```bash
pass-cli pat access revoke --pat-name "deploy-bot" --share-id <SHARE_ID>
```

--------------------------------

### Start Proton Pass CLI as SSH agent

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Starts the CLI as an SSH agent, creating a unix socket and periodically refreshing keys.

```bash
pass-cli ssh-agent start

```

--------------------------------

### pat renew - example with output

Source: https://protonpass.github.io/pass-cli/commands/personal-access-token

Example of renewing a token by name and the resulting new token string. The old token stops working after this command.

```bash
pass-cli pat renew --personal-access-token-name "deploy-bot" --expiration 3m
# PROTON_PASS_PERSONAL_ACCESS_TOKEN=pst_xxxx...xxxx::TOKENKEY

```

--------------------------------

### pass-cli item create login synopsis

Source: https://protonpass.github.io/pass-cli/commands/item

Shows the syntax for creating a login item.

```bash
pass-cli item create login [OPTIONS]

```

--------------------------------

### pass-cli item create synopsis

Source: https://protonpass.github.io/pass-cli/commands/item

Shows the syntax for the create subcommand.

```bash
pass-cli item create <ITEM_TYPE> [OPTIONS]

```

--------------------------------

### Start SSH agent with vault restrictions

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Restricts which vaults to monitor when starting the SSH agent, using --share-id or --vault-name parameters.

```bash
pass-cli ssh-agent start --share-id MY_SHARE_ID
pass-cli ssh-agent start --vault-name MySshKeysVault

```

--------------------------------

### Install Zsh completions on macOS/Linux

Source: https://protonpass.github.io/pass-cli/get-started/installation

Installs Zsh completion script for Proton Pass CLI on macOS/Linux. If ~/.zfunc is not in fpath, add the provided lines to ~/.zshrc.

```bash
mkdir -p ~/.zfunc
pass-cli completions zsh > ~/.zfunc/_pass-cli

```

--------------------------------

### Automate SSH Agent with systemd on Linux

Source: https://protonpass.github.io/pass-cli/commands/ssh-agent

Create the service file and then enable/start it using systemctl.

```ini
[Unit]
Description=Proton Pass SSH Agent

[Service]
ExecStart=/home/youruser/.local/bin/pass-cli ssh-agent start --socket-path %h/.ssh/proton-pass-agent.sock
Restart=on-failure

[Install]
WantedBy=default.target
```

```bash
systemctl --user enable --now proton-pass-ssh-agent.service
```
Tokens:
Raw