From 763b4dfc34d2129b2f2beccbb9a68995513493c1 Mon Sep 17 00:00:00 2001
From: Aneurin Barker Snook <aneurin@aneur.in>
Date: Sat, 19 Sep 2026 21:12:45 +0100
Subject: [PATCH] Add Dockerfile and README

Prebuilt glibc image for pass-cli: a small debian:bookworm-slim base with
a pinned, checksum-verified pass-cli binary, published so Alpine/musl-based
CI jobs can pull and run it without hitting missing glibc symbols
(fcntl64, __res_init, etc, which gcompat/libc6-compat don't shim).

No ENTRYPOINT, just CMD ["pass-cli"] -- callers running their own script
against pass-cli mount it in and pass it as the command directly
(`docker run image sh /script.sh`), no --entrypoint override needed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 Dockerfile | 32 +++++++++++++++++++++++++++++++
 README.md  | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 Dockerfile

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..0a5b41e
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,32 @@
+# pass-cli, glibc-linked, for hosts/CI where only an Alpine (musl) base is
+# otherwise available. pass-cli's Linux binary needs real glibc symbols
+# (fcntl64, __res_init, ...) that Alpine's gcompat/libc6-compat don't shim,
+# so it can't run in e.g. the docker:cli image directly.
+#
+# No ENTRYPOINT -- just CMD ["pass-cli"]. `docker run this-image` runs bare
+# pass-cli; `docker run this-image <args>` replaces CMD entirely, so a
+# caller running their own script against pass-cli (login, fetch a note,
+# parse it, etc.) just does `docker run this-image sh /path/to/script.sh`
+# with no --entrypoint override needed. The cost: `docker run this-image
+# --version` doesn't work as shorthand -- write `docker run this-image
+# pass-cli --version` instead.
+
+FROM debian:bookworm-slim
+
+ARG PASS_CLI_VERSION=2.3.3
+ARG PASS_CLI_SHA256=b5b49a8b3fd0af8830c0c1979f28ea0c90ccece73f59023a8bca8245d4b68da9
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl \
+    && curl -fsSL -o /usr/local/bin/pass-cli \
+         "https://proton.me/download/pass-cli/${PASS_CLI_VERSION}/pass-cli-linux-x86_64" \
+    && echo "${PASS_CLI_SHA256}  /usr/local/bin/pass-cli" | sha256sum -c - \
+    && chmod +x /usr/local/bin/pass-cli \
+    && apt-get purge -y curl \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+# No kernel keyring in a container -- store the session on disk instead.
+ENV PROTON_PASS_KEY_PROVIDER=fs
+
+CMD ["pass-cli"]
diff --git a/README.md b/README.md
index bc1c1ff..7a40e7c 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,56 @@
 # pass-cli Docker image
+
+A prebuilt, glibc-based container image for [Proton Pass
+CLI](https://protonpass.github.io/pass-cli/) (`pass-cli`).
+
+## Why this exists
+
+`pass-cli`'s official Linux binary is dynamically linked against glibc. It
+does not run under Alpine/musl, even with `gcompat` or `libc6-compat`
+installed — some of the symbols it needs (`fcntl64`, `__res_init`, ...) are
+glibc-specific and aren't shimmed. There's no official musl build and no
+official pass-cli image, so CI jobs that otherwise run in an Alpine-based
+container (like `docker:cli`) can't just `apk add pass-cli` or run the
+binary directly.
+
+This image is a small `debian:bookworm-slim` base with a pinned,
+checksum-verified `pass-cli` binary installed, published so that kind of job
+can pull it and run `pass-cli` (or a script that calls it) without needing
+its own glibc environment.
+
+## Usage
+
+There's no `ENTRYPOINT` -- just `CMD ["pass-cli"]`. Run bare:
+
+```sh
+docker run --rm code.aneur.in/cloud/pass-cli:<tag>
+```
+
+To run your own script against `pass-cli` instead (login, fetch an item,
+parse the result, etc.), mount it in and pass it as the command -- it
+replaces `CMD` entirely, no `--entrypoint` override needed:
+
+```sh
+docker run --rm \
+  -e PROTON_PASS_PERSONAL_ACCESS_TOKEN \
+  -v "$PWD/my-script.sh:/script.sh:ro" \
+  code.aneur.in/cloud/pass-cli:<tag> \
+  sh /script.sh
+```
+
+For one-off interactive use, prefix `pass-cli` explicitly, since args
+replace `CMD` rather than appending to it:
+
+```sh
+docker run --rm code.aneur.in/cloud/pass-cli:<tag> pass-cli --version
+```
+
+`PROTON_PASS_KEY_PROVIDER` is set to `fs` in the image by default, since a
+container has no kernel keyring for `pass-cli`'s usual session storage.
+
+## Updating the pinned version
+
+`PASS_CLI_VERSION` and `PASS_CLI_SHA256` are build args at the top of the
+`Dockerfile`. Bump both together — get the new version's hash from
+`https://proton.me/download/pass-cli/versions.json`, or download the binary
+and check it yourself with `sha256sum`.