pinchpass

Install PinchPass

PinchPass is a single Go binary. It has no runtime dependencies, starts an HTTP server on a random loopback port when you ask for a link, and exits when the secret arrives or the link expires. Pick whichever channel you already use.

MIT licensed Go 1.26+ macOS + Linux single dependency: golang.org/x/crypto

Pick a channel

Homebrew

The tap ships a cask for macOS and Linux.

shell
brew install --cask rubybear-lgtm/tap/pinchpass

Provides the pinchpass command. Update with brew upgrade --cask pinchpass.

npm, global

Installs the package and downloads the matching binary in a postinstall step.

shell
npm i -g @pinchpass/cli

Provides the pinchpass command and the Pi / OpenClaw extension. Update with npm update -g @pinchpass/cli.

npx, no install

Fetches the package and its binary on first use, then caches them.

shell
npx @pinchpass/cli request API_KEY

Good for a one-off request on a machine you do not want to change.

Prebuilt binary

Raw binaries from GitHub Releases, no package manager involved.

shell
curl -sL https://github.com/rubybear-lgtm/PinchPass/releases/latest/download/pinchpass-darwin-arm64 -o /usr/local/bin/pinchpass
chmod +x /usr/local/bin/pinchpass

See the asset names for the other platforms.

From source

Needs Go 1.26 or newer.

shell
go install github.com/rubybear-lgtm/pinchpass@latest

The version comes from the module metadata, so pinchpass --version still reports it.

Agent tool

Registers request_secret rather than a shell command.

shell
pi install npm:@pinchpass/cli

Also downloads the binary for link mode. Detail on agent integration.

Platforms

Releases cover Linux and macOS on both amd64 and arm64. Windows is not a published target, and there is no installer for it.

Prebuilt binaries

Release assets are named pinchpass-<os>-<arch>: pinchpass-linux-amd64, pinchpass-linux-arm64, pinchpass-darwin-amd64, and pinchpass-darwin-arm64. They are raw executables, not archives, so there is nothing to unpack:

shell
# macOS on Apple silicon
curl -sL https://github.com/rubybear-lgtm/PinchPass/releases/latest/download/pinchpass-darwin-arm64 -o /usr/local/bin/pinchpass
chmod +x /usr/local/bin/pinchpass

# macOS on Intel — pinchpass-darwin-amd64
# Linux x86_64   — pinchpass-linux-amd64
# Linux arm64    — pinchpass-linux-arm64

Each release publishes a checksums.txt of SHA-256 hashes beside the binaries. The npm postinstall verifies its own download against that file before installing, so a corrupted or substituted asset fails loudly rather than being installed. If you fetch a binary by hand, verify it yourself:

shell
shasum -a 256 pinchpass-darwin-arm64

Verify the install

  1. Confirm the binary runs and reports a version:

    shell
    pinchpass --version
# pinchpass v1.2.0 (abc1234)

    pinchpass version and pinchpass -version print the same thing. A build from source reports the module version rather than a release tag.

  2. Run a first request. This starts a server on 127.0.0.1 on a random port and prints a one-time link:

    shell
    pinchpass request TEST_KEY

  3. Open the printed link, type any value, and submit. The command blocks until the human submits or the TTL expires, then writes TEST_KEY="..." into .env and exits. When the request times out it exits non-zero and writes nothing.

  4. Read the CLI reference for every flag, or the security model before you use this for anything that matters.

Add the agent tool

If an agent is the thing that needs the secret, install the extension and let it call request_secret instead of shelling out.

Pi

shell
pi install npm:@pinchpass/cli

Registers the tool and the bundled skill.

OpenClaw

The same package ships an OpenClaw plugin manifest, exposing the same tool name with a $.raw backend. Install @pinchpass/cli and enable the plugin.

For every other agent, install the universal skill — one command, no per-platform plugin:

shell
# teach every detected agent
npx skills add rubybear-lgtm/pinchpass

# target specific agents
npx skills add rubybear-lgtm/pinchpass -a opencode -a claude-code -a openclaw

# install globally, available in every project
npx skills add rubybear-lgtm/pinchpass -g
Modal mode needs no binary

On Pi, the dialog collection mode reads the value straight into .env without starting a server or touching the network, so it works even when the pinchpass binary is not installed at all.

Updating

Update through the channel you installed with.
Installed withUpdate with
Homebrew brew upgrade --cask pinchpass
npm npm update -g @pinchpass/cli
go install go install github.com/rubybear-lgtm/pinchpass@latest
curl Re-run the curl command and chmod +x again.

Updating the npm package also replaces the downloaded binary: the postinstall compares the installed version against the package version and reinstalls when they differ, verifying the new asset against the release checksums. You do not need to remove the old binary first.

Troubleshooting

A rebuilt plugin still runs the old code in Pi

/reload does not pick up a rebuilt dist/, because Node's ESM cache serves whatever module was already loaded for that path. Restart Pi after a rebuild. /reload only helps the first time, before anything is cached.

pinchpass: command not found after installing the Pi tool

The Pi package downloads a binary, and link mode resolves it by searching PATH, ~/.local/bin, ~/.openclaw/bin, and ~/.pi/bin. Check those locations before adding anything to PATH. Modal mode does not need the binary at all.

The command just sits there

That is the design. pinchpass request blocks until the human submits or the TTL expires, then exits. In a script or an agent loop, treat it as a long-running call and give it a timeout larger than the -ttl you asked for.

My request timed out

Nothing was written. The human mode prints ❌ Request timed out. No secret was saved. and exits non-zero; with -json the final object is {"success": false, "message": "Request timed out or failed."}. Ask again — a link cannot be reused or revived.

The form says "Missing encryption key"

The #k= fragment was lost, usually because a chat client or a redirect stripped everything after #. The page then disables the submit button on purpose, since it has no key to encrypt with. Send the full URL from the CLI output verbatim, or request a new link.

Next

  • CLI reference — every flag, the JSON output, and how .env is written.
  • Security model — what the relay sees, the exact crypto, and what this does not protect against.
  • Agent integration — the tool, the skill, and a safe agent loop.
  • FAQ — the questions that come up first.