Proton Pass Provider

Why pass-cli upgrades can break this provider

Proton Pass has no public API and no SDK, so this provider drives the official pass-cli executable and inherits whatever that executable does.

Proton support confirmed in August 2026 that its support for pass-cli covers only what the pass-cli changelog publishes, that backward incompatible changes can ship in a patch release with no advance notice, and that it is reasonable to expect more of them. Three such releases have already changed behaviour Monosecret depends on, most recently pass-cli 2.2.4, which broke every Proton Pass operation until Monosecret 0.2. See pass-cli compatibility.

The practical consequence is that upgrading pass-cli can break secret resolution on a machine where nothing about Monosecret changed, and the repair then waits on a Monosecret release. Install a pass-cli version you have tested and upgrade it deliberately, as described in Pinning a pass-cli version.

This is unfortunate. Providers built on a versioned API or on a vendor interface with a compatibility policy do not break this way. If Proton publishes a stable API, an SDK, or a compatibility policy for pass-cli, we would build on it instead.

The Proton Pass provider integrates with Proton Pass for end-to-end encrypted cloud secret storage.

At a glance

Provider	protonpass
URI	protonpass://[vault_name[/title-template]]
Access	Read and write
Best for	End-to-end encrypted cloud storage through Proton Pass
Authentication	A pass-cli login or personal access token
Default storage	Note item {project}/{profile}/{key} in the monosecret vault
Requires	Official pass-cli, pinned to a version you have tested (see compatibility)

Quick start

# Set a secret
$ monosecret set DATABASE_URL --provider protonpass://Personal
Enter value for DATABASE_URL: postgresql://localhost/mydb

# Get a secret
$ monosecret get DATABASE_URL --provider protonpass://Personal

# Run with secrets
$ monosecret run --provider protonpass://Personal -- npm start

Setup

Prerequisites

• Proton Pass CLI (pass-cli) - download from proton.me/pass/download
• A Proton account, signed in via pass-cli login
• A vault to store secrets in (e.g. pass-cli vault create monosecret)
• A pass-cli version that works with your Monosecret release, see pass-cli compatibility

Authentication

For local use, sign in interactively:

$ pass-cli login

For CI, use a personal access token as shown in CI/CD.

pass-cli compatibility

Each of these pass-cli releases changed behaviour the provider relies on:

pass-cli	What changed	Monosecret
2.0.3 (2026-05-19)	item list output shape	Handled in 0.1.1+
2.1.0 (2026-05-20)	Agent sessions reject audited item operations that carry no reason	Handled in 0.1.0+, see Agent sessions
2.2.4 (2026-07-31)	pass-cli test removed	Handled in 0.2+ (#279)

Monosecret probes the session once per run before any read or write. Monosecret 0.2.0 and earlier probe with pass-cli test, so on pass-cli 2.2.4 and later every Proton Pass operation fails with:

Provider operation failed: error: unrecognized subcommand 'test'

Monosecret 0.2+ tries pass-cli info and falls back to pass-cli test, so it works with supported pass-cli releases regardless of which check that release carries. info is preferred because it runs behind the CLI’s authentication gate and so reports whether a valid session is present, while test only proved that Proton’s servers were reachable. A pass-cli carrying neither is reported as incompatible with your Monosecret release rather than surfacing the CLI’s usage text.

On Monosecret 0.2.0 and earlier, use pass-cli 2.2.3, the last release published before pass-cli test was removed.

Pinning a pass-cli version

Install a specific release instead of tracking the latest build, and point Monosecret at it with MONOSECRET_PROTONPASS_CLI_PATH:

$ curl -Lo ~/.local/bin/pass-cli-2.2.3 \
    https://github.com/protonpass/pass-cli/releases/download/2.2.3/pass-cli-linux-x86_64

$ chmod +x ~/.local/bin/pass-cli-2.2.3

$ export MONOSECRET_PROTONPASS_CLI_PATH="$HOME/.local/bin/pass-cli-2.2.3"

Every release publishes a .sha256 file next to each binary; verify it before use. Pin the same version in CI rather than installing the latest pass-cli on each run, and treat a pass-cli upgrade as a change worth testing: run monosecret check against the new version before rolling it out.

Configuration

URI format

protonpass://[vault_name[/title-template]]

• vault_name: Target vault (defaults to monosecret)
• title-template: Item title pattern supporting {project}, {profile}, {key} placeholders

URI examples

# Default vault ("monosecret")
protonpass://

# Specific vault
protonpass://Work

# Specific vault and custom title template
protonpass://Work/{project}/{profile}/{key}

Project configuration

monosecret.toml

[providers]
team = "protonpass://Work"

[profiles.production]
DATABASE_URL = { description = "Database URL", providers = ["team"] }

Storage model

Secrets are stored as note items. The vault defaults to monosecret, and the item title defaults to {project}/{profile}/{key}. The URI can select another vault or replace the title template.

Use existing secrets

A secret’s ref field names an existing item instead: item is the exact item title, whose note is read (field is not supported). Reads and writes target that item in place.

[profiles.production]
DATABASE_URL = { description = "DB", ref = { item = "Production Database" }, providers = [
  "protonpass://Work",
] }

CI/CD

# Create a token
$ pass-cli personal-access-token create --name ci --expiration 1y

# Authenticate in CI (store the token as a CI secret)
$ pass-cli login --pat $PROTON_PASS_PAT

$ monosecret run -- deploy

Advanced configuration

Agent sessions

pass-cli 2.1.0 introduced agent sessions, which require a PROTON_PASS_AGENT_REASON to be set for audited item operations (reading, creating, and deleting items). Monosecret sets this automatically, so existing secrets resolve correctly under an agent session.

The reason recorded in the Proton Pass audit log is resolved in this order:

1. The --reason flag (or MONOSECRET_REASON environment variable):

   $ monosecret run --reason "Deploying app from CI" -- ./deploy.sh
   

   When using the Rust SDK, set it for the session with with_reason:

   use monosecret::Secrets;
   
   let spec = Secrets::load()?.with_reason("Deploying app from CI");

2. The PROTON_PASS_AGENT_REASON environment variable read by pass-cli:

   $ export PROTON_PASS_AGENT_REASON="Deploying app from CI"
   

3. A default that identifies the Monosecret version (for example, monosecret/0.2.0 (https://ifiokjr.github.io/monosecret/)).

To force a meaningful reason instead of falling back to the default, use the require_reason policy in monosecret.toml. It defaults to "agents", so sessions Monosecret detects as AI agents must explain why they read a secret. Detection is heuristic; set it to true to require a reason from every Monosecret caller. Monosecret then refuses operations through Monosecret that do not supply an explicit reason.