PassNinja

passninja

Command-line interface for the PassNinja REST API. Wraps /v1/pass_templates, /v1/passes, and /v1/webhooks so you can manage Apple Wallet and Google Wallet passes from the shell.

Install

macOS / Linux (Homebrew)

brew tap flomio/passninja

brew install passninja

Windows (PowerShell)

irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex

From cmd.exe:

powershell -ExecutionPolicy Bypass -Command "irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex"

The script detects your CPU (amd64, arm64, or 386), downloads the matching binary from the latest GitHub release, verifies its SHA256, drops it in %LOCALAPPDATA%\Programs\passninja\, and adds that directory to your user PATH. No admin needed; re-running upgrades in place.

Pin a specific version, or override the install directory:

$env:PASSNINJA_VERSION = 'v1.2.3'

$env:PASSNINJA_INSTALL_DIR = 'C:\tools\passninja' irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex

Windows (Scoop)

If you already use Scoop:

scoop bucket add flomio https://github.com/flomio/scoop-passninja

scoop install passninja

Claude Desktop (one-click .mcpb install)

For chat-driven pass workflows, install the PassNinja MCP server into Claude Desktop:

1. Download passninja.mcpb from the latest release.
2. Double-click the file. Claude Desktop opens an install dialog showing the 31 tools the server exposes (pass templates, issued passes, webhooks, scan-event applications and readers).
3. The dialog prompts for your API key and account ID — get them at https://www.passninja.com/settings → API key.
4. Hit Install, restart Claude Desktop, then ask Claude things like:

List my passninja pass templates and tell me how many passes are installed on each.

Issue a new pass on ptk_0x002 for jane@example.com.

The bundled binary is code-signed with Apple Developer ID and notarized, so macOS Gatekeeper accepts it without prompts. Same .mcpb works on macOS (universal), Linux (amd64), and Windows (amd64).

The server is also listed in the official MCP Registry as io.github.flomio/passninja-cli, so any MCP client that consumes the registry can discover and install it automatically.

Authenticate

passninja login

Opens www.passninja.com in your browser. If you're already signed in there,

no password is asked. The CLI keeps a login session in your OS keychain —

never your account API key.

The session's access token refreshes automatically; the session itself ends 30 days after login, and passninja logout ends it immediately (locally and on the server). If you run any command while logged out at a terminal, the browser login starts on its own.

On a machine without a browser (SSH, containers), log in with a code entered from any other device:

passninja login --device

For CI and scripts, use an API key via env / flags instead:

export PASSNINJA_API_KEY=...        PASSNINJA_ACCOUNT_ID=aid_0x002

passninja --api-key=... --account-id=... pass-template list

Precedence: API key (flags > env > ~/.passninja.yaml) > login session > legacy ~/.passninja-auth.json (written by passninja auth). An API key you set explicitly always wins, so automation is never redirected to a personal session.

The same precedence applies to the MCP server: passninja mcp (started by Claude Desktop and other MCP clients) uses PASSNINJA_API_KEY / PASSNINJA_ACCOUNT_ID from its environment, else your login session. It never opens a browser itself — run passninja login once first.

Stdio MCP server

The CLI also doubles as a Model Context Protocol server. The .mcpb install above wires this into Claude Desktop, but you can hook it into any MCP client (Cursor, Cline, Zed, etc.) by configuring the client to launch:

passninja mcp

Tool surface (snake_case names mirror the CLI subcommands):

whoami

pass_template_{list, get, required_fields, reader_config, create, delete} pass_{list, get, create, update, delete, raw, decrypt} webhook_{list, get, create, delete, results}

Each tool's input schema, destructive-hint annotations, and rich descriptions let the LLM self-discover correct usage without external documentation.

Commands

passninja login [--device] [--no-browser]           Log in through your browser (session in OS keychain)

passninja logout End the login session here and on the server passninja auth Save an API key to ~/.passninja-auth.json (legacy) passninja whoami Show the active credential / account passninja version

passninja pass-template list passninja pass-template get passninja pass-template required-fields passninja pass-template reader-config # NFC reader config (merchant id, collector, EC keys) passninja pass-template create --name --platform --style [config flags] # enterprise only passninja pass-template update [--name --set --remap --show/--hide --require/--optional] [config flags] [--replace] # enterprise only passninja pass-template delete [--yes] # enterprise only

config flags (create + update): --constrain-device/-browser/-ip,

--disable-apple-sharing/-google-sharing, --auto-recharge --balance-trigger --top-up-target

passninja pass create [--field k=v | --data @file.json | --data ' '] passninja pass list passninja pass get passninja pass raw passninja pass update [--field k=v | --data ... | --replace] passninja pass delete [--yes] passninja pass decrypt [--payload | --payload-file | ] [--platform apple]

Google Smart Tap is session-bound — use reader serve on the reader host

Enterprise only:

passninja webhook create --name --url --event [--event ...] [--pass-template ptk_0x...] passninja webhook list [--page --per-page --pass-template] passninja webhook get passninja webhook delete [--yes] passninja webhook results [--page --per-page]

Scan event system (premium):

passninja application list passninja application get passninja application create --name --pass-template ptk_0x... [--kind log|validate|forward] [--rescan-window ] [--endpoint-url ] [--bearer-token ] [--timeout-ms <100-8000>] [--on-endpoint-error accept|reject] [--description] passninja application update [--name --description --kind --rescan-window --endpoint-url --bearer-token --timeout-ms --on-endpoint-error --active/--inactive] passninja application delete [--yes]

passninja reader list passninja reader get passninja reader create --name --location --application app_0x... [--application ...] # prints the token once passninja reader update [--name --location --status active|revoked --application ...] passninja reader rotate-token [--yes] passninja reader delete [--yes] passninja reader config # merged reader config across bound templates passninja reader serve --token rdr_... [--pcsc [--pcsc-reader ] | --listen host:port] [--platform apple|google] [--heartbeat 5m | --no-heartbeat] [--serial --manufacturer --model --firmware --source] [--on-accept ' '] [--on-reject ' ']

Output formats

Set a session-wide default via ~/.passninja.yaml:

default_output: json    # one of: table | json | plaintext

base_url: https://api.passninja.com/v1

Webhook events

The CloudEvents 1.0 type taxonomy emitted by passninja-site:

Reserved for future use: pn.pass.issued, pn.pass.deleted, pn.pass_template.created, pn.pass_template.updated, pn.pass_template.deleted.

Running a reader host

Cloud-connected readers (VTAP Cloud, Famoco Tap&Go) post scans to PassNinja themselves. A simple reader — Reyax RYRR30D, ACS WalletMate, Elatec TWN4 — has no cloud connection of its own, so reader serve supplies one: it takes the values the reader captures, submits them as scan events, and applies the LED/beep instruction the server returns.

Setup is three steps, and only the last one runs on the reader host:

# 1. an application decides what a scan means for one pass template

passninja application create --name "Front gate" --kind validate \ --pass-template ptk_0x216 --rescan-window 14400

2. a reader binds to it; the token is printed once — save it

passninja reader create --name "Front gate" --location "Gate 2" \ --application app_0x1

3. on the reader host (a Raspberry Pi, a kiosk PC, …)

passninja reader serve --token rdr_... --pcsc # attached PC/SC reader my-reader-daemon | passninja reader serve --token rdr_... # or any daemon

serve authenticates as that one reader with its bearer token — a reader host never needs, and should never hold, your account API key.

Tap values arrive from one of three sources:

• `--pcsc` drives an attached PC/SC contactless reader (ACS WalletMate / WalletMate II, incl. the Mini module) directly — no separate daemon. The host runs the wallet flows itself: on an Apple tap it captures the VAS cryptogram; on an Android tap it has the server pre-sign the Smart Tap session mid-tap (the collector key never leaves PassNinja), negotiates the secure channel, and captures the encrypted bundle. Both are submitted for server-side decryption — the host holds no key material. First-generation WalletMates ship with RF polling disabled; serve enables it automatically when the vendor CCID driver is installed. Needs a native (cgo) build on macOS/Linux — go install and Homebrew builds qualify.
• stdin (one value per line) — pipe any reader daemon's output in.
• `--listen 127.0.0.1:8080` — a loopback HTTP endpoint a driver POSTs to.

For stdin/HTTP, a value that looks like raw captured APDUs is forwarded for server-side decryption; anything else is treated as an already-decrypted pass serial.

Each result is one JSON object on stdout:

{"scanId":"9f8e7d6c-…","result":"accepted","pass":{"passTemplate":"ptk_0x216","passId":"fee4a257185906b92a"},

"readerInstructions":{"success":true,"led":"green","beep":true,"message":"Accepted"}}

To drive a physical LED, use the outcome hooks — they receive $PN_RESULT, $PN_LED, $PN_MESSAGE, $PN_PASS, $PN_SCAN_ID, and — when a forward application answered — $PN_FORWARD_BODY (the endpoint's JSON reply). On a forward application, $PN_MESSAGE is the endpoint's message verbatim and the printed scan JSON carries the reply under forwardResponse:

passninja reader serve --token rdr_... \

--on-accept 'gpioset 0 17=1' --on-reject 'gpioset 0 27=1'

Heartbeats (default every 5m) report liveness plus the hardware identity yo