Passport CLI and bridge

passport-bridge connects MCP clients to a Passport workspace without putting a long-lived token in the client configuration. The same package also installs passport, a polished command-line client for terminal agents, scripts, and CI.

Both binaries use the Passport gateway. Member-authenticated CLI calls share tool access, client selection, guardrails, approvals, and activity logging with native MCP clients. Non-interactive agent keys still use their assigned pass, client selection, guardrails, middleware, and audit trail, but do not raise a member's interactive approval prompt.

Install

npm install --global passport-bridge

Node.js 20 or newer is required.

Passport CLI

Sign in once, then search and run the tools your workspace permits:

passport login --cloud https://passport.example.com --workspace ws_example
passport status
passport search "open issues"
passport describe github_search_issues
passport run github_search_issues '{"query":"SSO"}'

passport help [command] documents every option. passport help and passport version work without a profile or network connection.

Remote Passport servers must use HTTPS. Plain HTTP is accepted only for local development on localhost, 127.0.0.0/8, or ::1. Self-hosted deployments should terminate HTTPS before using interactive profiles or agent keys.

Passport CLI 0.6.1 requires gateway MCP serverInfo passport version 0.5.0 or newer and the exact four-tool governed CLI protocol. Older servers fail clearly before the CLI makes a tool call.

Commands

| Command | Purpose | | --- | --- | | login | Complete device sign-in and save a rotating CLI credential. | | logout | Revoke the credential and remove its local profile. | | status | Show the workspace, member, client, and visible MCP connection states. | | doctor | Check runtime, credential-store safety, configuration, reachability, authentication, and CLI protocol compatibility. | | search [query] | Search permitted tool definitions. An empty query lists the complete catalog. | | describe <tool> | Print one exact definition and its full parameter schema. | | run <tool> [json] | Run a tool through Passport governance. | | connect [app...] | Show secure member connection links and optionally wait for completion. | | resources [uri] | List or read MCP resources. | | prompts [name] | List or get MCP prompts. | | completion <shell> | Generate completion for Bash, Zsh, or Fish without a profile or network. | | help [command] | Show general or command-specific help. | | version | Show the package version and locally resolvable profile context. |

Every command accepts --profile <name>, --json, --timeout <seconds>, --quiet, and --caller <id> where applicable.

Diagnostics

Run diagnostics before opening a support ticket or promoting a CLI release:

passport doctor --profile cli@ws_example
passport doctor --profile cli@ws_example --json

doctor checks Node.js, the credential file's shape/ownership/mode, auth configuration, HTTPS policy, /healthz, the authenticated MCP handshake, serverInfo compatibility, and the exact four-tool CLI protocol. It never prints credential values, response bodies, member identity, or all stored profile names. A failed required check returns exit 1 while still emitting the complete diagnostic report; configuration errors include a concrete fix.

Shell completion

Completion is generated locally and performs no profile or network lookup:

# Bash
mkdir -p ~/.local/share/bash-completion/completions
passport completion bash > ~/.local/share/bash-completion/completions/passport

# Zsh (ensure ~/.zfunc is in fpath before compinit)
mkdir -p ~/.zfunc
passport completion zsh > ~/.zfunc/_passport

# Fish
mkdir -p ~/.config/fish/completions
passport completion fish > ~/.config/fish/completions/passport.fish

Tool arguments

Pass a JSON object positionally:

passport run github_search_issues '{"query":"SSO","limit":10}'

Read the object from stdin:

printf '%s' '{"query":"SSO"}' | passport run github_search_issues --args -

Or build it without shell JSON escaping:

passport run github_search_issues --set query=SSO --set-json limit=10

These forms are mutually exclusive. --set produces strings and --set-json accepts any valid JSON value.

Approvals and connections

An approval-required call exits immediately with code 4 and its approval ID. --wait <seconds> retries only after a definite structured approval_pending response:

passport run github_create_issue '{"title":"Customer report"}' --wait 90

The CLI never retries a call after a network failure or timeout because the execution outcome may be unknown.

For an MCP that needs member sign-in:

passport connect github --open --wait 120

Without app names, connect uses one aggregate link when several visible MCPs need sign-in. Agent-key principals receive status and member guidance but cannot mint browser links.

Resources and prompts

passport resources
passport resources passport+github://welcome
passport resources passport+github://image --out image.png

passport prompts
passport prompts github_summarize --set note=welcome

Human mode writes text content to stdout. Binary or other non-text content requires --out <file> or --json.

Output contract

With --json, stdout contains exactly one JSON value and no progress text. Hints and warnings use stderr. The success value for each command is:

| Command | JSON value | | --- | --- | | login | {profile, endpoint, client, surface} | | logout | {profile, removed, revoked} | | status | {workspace, member, endpoint, auth, profile?, client, mcps} | | doctor | {version,ok,auth,profile?,profileCount,endpointOrigin?,server?,checks} (also emitted when checks fail). | | search | The gateway search payload, including results or catalog and note. | | describe | One tool definition. | | run | The complete governed MCP tool result, preserving every content block and upstream structuredContent. | | connect | The gateway connection payload, including connections and optional connectAllUrl. | | resources | The MCP list or read result. | | prompts | The MCP list or get result. | | completion | {shell,script}. Human mode emits the raw completion script. | | help | {command, help} | | version | {version, endpoint?, profile?} |

JSON errors have a stable shape:

{"error":"...","cause":"blocked","exitCode":5,"app":"github"}

approvalId and app are included when supplied by the gateway.

| Exit | Meaning | | ---: | --- | | 0 | Success | | 1 | Network, timeout, server, or unsupported-content error | | 2 | Missing, expired, or revoked authentication | | 3 | The MCP needs member sign-in | | 4 | Approval is pending | | 5 | Policy, guardrail, selection, or approval denial | | 6 | Invalid usage or unknown tool/app |

Profiles

Credentials are named slots in one file, ~/.passport/credentials.json, with mode 0600. Set PASSPORT_HOME to change its directory. Profile resolution is:

1. --profile <name>
2. PASSPORT_PROFILE
3. the sole stored profile

If several profiles exist, select one explicitly. The credential store is shared with passport-bridge and refresh exchanges are coordinated across processes.

Profile names are 1-80 letters, numbers, dots, underscores, @ signs, or hyphens, and must start with a letter or number. Credential updates are atomically replaced at mode 0600, including when several profiles rotate concurrently.

logout always removes the local slot. If Passport cannot be reached to confirm server-side revocation, it prints a warning so the user knows the remote credential could not be revoked.

Use a distinct policy identity for a particular agent while keeping the CLI protocol:

passport login \
  --cloud https://passport.example.com \
  --workspace ws_example \
  --client claude-code \
  --profile claude-code@ws_example

The credential surface remains cli; claude-code is the separate client identity used for policy, selection, devices, and activity attribution.

Caller attribution

--caller <id> adds cooperative activity detail for the agent behind the CLI call. Values use lowercase letters, numbers, and hyphens, up to 24 characters. The CLI otherwise detects Claude Code, Codex, OpenCode, Cursor, or Gemini CLI from their environment markers.

Caller attribution is self-reported, not an attested identity. The gateway only accepts it from a CLI-surface credential or a CLI agent-key request.

Headless and CI authentication

Supply an existing Passport agent key from the job's secret manager:

export PASSPORT_ENDPOINT=https://passport.example.com/mcp
export PASSPORT_AGENT_KEY="$CI_PASSPORT_AGENT_KEY"
passport search "deployment status" --json

Environment authentication wins over stored profiles, persists nothing, and sends the agent key directly to the gateway. Do not combine it with --profile. PASSPORT_PROFILE is only for stored interactive credentials.

Agent keys are deliberately non-interactive. Their assigned pass, app selection, guardrails, middleware, and audit trail still apply, but action-time member approval prompts do not. Use a member profile for work that must pause for a human's one-off approval.

Package verification and updates

Maintainers can build the exact npm tarball, validate its required files, and write a SHA-256 sidecar without registry credentials:

npm run pack:verified
sha256sum -c passport-bridge-<version>.tgz.sha256

The command also reports npm's SHA-1 shasum and SHA-512 integrity value for release notes or an external artifact manifest. The package declares public access and points support/source inquiries at Passport's public release repo.

The CLI deliberately performs no background registry request, telemetry, or automatic self-update. Check explicitly with npm view passport-bridge version and upgrade with npm install --global passport-bridge@latest. npm provenance attestation is intentionally deferred until publication moves to a trusted OIDC publisher; local/manual publishing cannot produce a trustworthy attestation. Platform signing is not applicable to these JavaScript npm bins.

MCP stdio bridge

Create a bridge profile:

passport-bridge login \
  --cloud https://passport.example.com \
  --workspace ws_example \
  --client cursor \
  --profile cursor@ws_example

Configure the MCP client to launch:

passport-bridge serve --profile cursor@ws_example

The bridge exchanges its file-backed refresh credential for short-lived access tokens, persists rotations, coordinates concurrent processes, and forwards tools, resources, prompts, cancellation, progress, and tool-list changes over stdio. passport-bridge status checks stored bridge profiles, and passport-bridge logout --profile <name> revokes one.

Run passport-bridge --help for the complete bridge command surface or passport-bridge --version to print the installed package version.