# Proton Pass CLI Command Reference

> Reference: https://protonpass.github.io/pass-cli/

## Auth Commands

| Command | Description |
|---------|-------------|
| `pass-cli login [--interactive [USERNAME]]` | Interactive login (password, TOTP, extra pwd) |
| `pass-cli login --personal-access-token <TOKEN>` | PAT-based login for automation |
| `pass-cli login` | Web browser OAuth login |
| `pass-cli logout` | End current session |
| `pass-cli info` | Show account/session info |
| `pass-cli test` | Test connection & auth |

## Vault Commands

| Command | Description |
|---------|-------------|
| `pass-cli vault list [--output json]` | List all vaults |
| `pass-cli vault create --name NAME` | Create vault |
| `pass-cli vault update --share-id SID --name NEW_NAME` | Rename vault |
| `pass-cli vault delete --share-id SID` | Delete vault (permanent) |
| `pass-cli vault share SID EMAIL [--role ROLE]` | Share vault |
| `pass-cli vault transfer SID MEMBER_SID` | Transfer ownership |
| `pass-cli vault member list --share-id SID` | List members |

## Item Commands

| Command | Description |
|---------|-------------|
| `pass-cli item list [VAULT] [--output json]` | List items |
| `pass-cli item create login [OPTIONS]` | Create login item |
| `pass-cli item create note [OPTIONS]` | Create note item |
| `pass-cli item create ssh-key generate [OPTIONS]` | Generate SSH key |
| `pass-cli item create ssh-key import --from-private-key PATH` | Import SSH key |
| `pass-cli item view --share-id SID --item-id IID [--output json]` | View item |
| `pass-cli item view pass://SID/IID/FIELD [--output json]` | View by URI |
| `pass-cli item update --share-id SID --item-id IID --field K=V` | Update fields |
| `pass-cli item delete --share-id SID --item-id IID` | Delete item |
| `pass-cli item share --share-id SID --item-id IID EMAIL --role ROLE` | Share item |
| `pass-cli item attachment download [OPTIONS]` | Download attachment |
| `pass-cli item alias create [OPTIONS]` | Create alias |

## View Item Contents

| Command | Description |
|---------|-------------|
| `pass-cli view pass://VAULT/ITEM/FIELD` | View/resolve a secret reference |
| `pass-cli run [--env-file FILE] -- COMMAND` | Run command with injected secrets |
| `pass-cli inject [--in-file FILE] [--out-file FILE]` | Process template with secrets |

## TOTP

| Command | Description |
|---------|-------------|
| `pass-cli item view --share-id SID --item-id IID --field totp` | Get TOTP code |

## SSH Agent

| Command | Description |
|---------|-------------|
| `pass-cli ssh-agent load` | Load keys into system SSH agent |
| `pass-cli ssh-agent start` | Start as SSH agent (foreground) |
| `pass-cli ssh-agent daemon start` | Start SSH daemon (background) |
| `pass-cli ssh-agent daemon status` | Check daemon status |
| `pass-cli ssh-agent daemon stop` | Stop daemon |

## Settings & Other

| Command | Description |
|---------|-------------|
| `pass-cli settings [--default-vault NAME] [--default-format FORMAT]` | Configure defaults |
| `pass-cli password generate [LENGTH]` | Generate password |
| `pass-cli password passphrase [WORD_COUNT]` | Generate passphrase |
| `pass-cli share --vault-name VAULT EMAIL [--role ROLE]` | Share vault/items |
| `pass-cli pat create [OPTIONS]` | Create personal access token |
| `pass-cli pat revoke <PAT_ID>` | Revoke a PAT |
| `pass-cli update` | Self-update pass-cli binary |
| `pass-cli user info` | Detailed user info |
| `pass-cli agent` | Agent management |

## Secret Reference Syntax

```
pass://<vault-identifier>/<item-identifier>/<field-name>
```

- vault-identifier: Share ID or vault name
- item-identifier: Item ID or title
- field-name: case-sensitive field name (password, username, email, url, note, totp, custom)

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `PROTON_PASS_PASSWORD` | Interactive login password |
| `PROTON_PASS_PASSWORD_FILE` | Path to password file |
| `PROTON_PASS_TOTP` | TOTP code for login |
| `PROTON_PASS_TOTP_FILE` | Path to TOTP file |
| `PROTON_PASS_EXTRA_PASSWORD` | Extra password |
| `PROTON_PASS_EXTRA_PASSWORD_FILE` | Path to extra password file |
| `PROTON_PASS_PERSONAL_ACCESS_TOKEN` | PAT for automation login |
| `PROTON_PASS_SSH_KEY_PASSWORD` | SSH key passphrase |
| `PROTON_PASS_SSH_KEY_PASSWORD_FILE` | Path to SSH key passphrase file |
| `PROTON_PASS_SSH_DAEMON_PIDFILE` | Custom PID file path |
| `PROTON_PASS_CLI_PATH` | Custom binary path (used by the Hermes skill) |