Passport CLI

Setting up your own computer? npx passport-bridge@latest init does it in one pass: see the developer quickstart. Passport CLI is for terminal coding agents and automation. It talks to the same Passport connection as Claude, Cursor, and ChatGPT — same access rules, Safety, approvals, and Activity log. Prefer the normal Add agent setup for apps with a GUI (Cursor chat, VS Code chat, Claude Desktop, Claude.ai, ChatGPT). Claude Code and Codex CLI can use either path; using the CLI does not turn off other connections. Works on Windows, Linux, and macOS. Needs Node.js 22.23.2 or newer.

Windows (PowerShell)
Linux
macOS

npm install --global passport-bridge
passport version
passport login
passport status
passport search ""

npm install --global passport-bridge
passport version
passport login
passport status
passport search ""

npm install --global passport-bridge
passport version
passport login
passport status
passport search ""

Install once

The passport-bridge package ships both passport and passport-bridge.

npm i -g passport-bridge
passport version

Run passport login. It opens your browser. Sign in with Google, GitHub, or a code sent to your email, check that the code on the page matches your terminal, then click Connect. New to Passport? Name your workspace on the same page and you’re in.

passport login
passport status
passport doctor

The terminal prints what to expect:

Sign in to Passport
Opening your browser... (or open https://passportmcp.com/cli?code=HJKT-WQRM)
Confirm this code in the browser: HJKT-WQRM
Waiting... (Ctrl-C to cancel)

Signed in to Acme.
Next: passport status

Codes expire after 10 minutes and work once. Nothing connects until you click Connect, and Deny stops the terminal. If you’re already signed in to Passport in that browser, you’ll see your workspace straight away; Use a different account picks another. Login stores a rotating credential in ~/.passport/credentials.json with owner-only permissions and makes that profile active.Already know the workspace? passport login --workspace ws_… signs in to it directly. Self-hosted deployments also pass --cloud <origin>. On SSH, CI, or another headless host, add --no-open so Passport prints the link instead of launching a browser; open it on any device:

passport login --no-open

To switch later on a machine with more than one profile, inspect and select the local active profile explicitly:

passport profiles
passport use cli@ws_…

Search, inspect, and run

search returns namespaced tool names. Pass one directly to describe or run; no name translation is required.

passport search "issues"
passport describe github_search_issues
passport run github_search_issues '{"query":"SSO"}'

Commands

Command	Purpose
`passport status`	Show the workspace, profile, policy agent, and visible app connection states.
`passport doctor`	Check the runtime, credential-store safety, endpoint, authentication, and exact CLI protocol without exposing credentials.
`passport search [query]`	Discover allowed, namespaced tools. An empty query lists the visible catalog.
`passport describe <tool>`	Print a tool’s description, read-only flag, and full parameters schema. JSON also exposes `name` and `inputSchema` aliases.
`passport run <tool> [json-args]`	Execute a governed tool call. Use `--args -` for stdin or repeat `--set` / `--set-json`.
`passport connect [app...]`	Get or open a personal-account connection flow. Add `--wait <sec>` to wait for completion.
`passport resources [uri]`	List resources or read one URI.
`passport prompts [name]`	List prompts or get one, with repeatable `--set key=value` arguments.
`passport discover`	Scan supported global MCP configuration and submit privacy-minimized inventory. Managed-policy violations exit `5`.
`passport completion <bash\|zsh\|fish>`	Generate shell completion locally without a profile or network request.
`passport profiles` / `use <name>`	List local profiles or select the active profile without network access.
`passport login` / `logout`	Create or revoke a named local profile.
`passport ready --json`	Report machine-readable local readiness for automation.
`passport help [verb]` / `version`	Inspect the CLI without a profile or network connection.

Every command accepts --profile, --json, --timeout, --quiet, and --caller. passport discover is how Inventory → Outside Passport findings reach Passport; it is the only source. It is headless and cross-platform, which suits an onboarding script or a scheduled MDM job, and it reports limited configuration metadata only—never paths, commands or arguments, environment values, headers, credentials, endpoint paths or query strings, prompts, files, tool payloads, or traffic. See Inventory.

Diagnose and complete

doctor returns every check even when one fails. Human output includes a safe, actionable fix; --json returns a stable report suitable for support automation. Neither form prints credential values, response bodies, or member identity.

passport doctor
passport doctor --json

passport version --json is also offline. It returns version, profileCount, profileSelected, selectionSource, next, and optional endpoint/profile fields. passport ready --json runs the local, authentication, server, and exact CLI-protocol preflight and returns ready, ok, auth/profile context, server, and checks; gate on its ready value and exit code rather than parsing human output. Install generated completion in the standard location for your shell:

# Zsh
mkdir -p ~/.zfunc
passport completion zsh > ~/.zfunc/_passport

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

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

JSON and exit-code contract

With --json, stdout contains exactly one JSON value. Hints and warnings go to stderr, so an agent can pipe results without stripping human output. JSON errors have this stable shape:

{
  "error": "A short message",
  "cause": "approval_pending",
  "exitCode": 4,
  "approvalId": "optional",
  "app": "optional",
  "hint": "optional safe remediation",
  "next": [{ "argv": ["passport", "status"], "description": "optional concrete action" }],
  "retry": { "command": "run", "tool": "optional", "waitSeconds": 120, "arguments": "reuse_original" },
  "remediation": { "action": "optional_machine_action", "description": "safe guidance" }
}

Exit	Meaning
0	Success.
1	Network, server, or ambiguous execution error. Do not retry automatically.
2	Authentication or profile selection is missing. Run `passport profiles`, `passport use <name>`, or `passport login`.
3	A personal app connection or member action is required. Follow `next` or `remediation`; agent keys fail fast instead of waiting for browser OAuth.
4	Approval is pending. The result includes the approval id.
5	Policy, a guardrail, agent selection, or approval denial blocked the call.
6	Usage error or unknown tool.

passport run --wait <sec> retries only a definite approval_pending response. It never retries a timeout or network failure because the execution outcome could be ambiguous. For passport describe <tool> --json, tool and parameters remain the Passport-native fields. The response also includes the conventional aliases name (same value as tool) and inputSchema (same value as parameters); agents can use either vocabulary without translating tool definitions.

Profiles and attribution

The default profile uses cli as its policy agent. Login activates the newly completed profile. When no explicit or environment selector and no valid active profile are present, CLI 0.8.1 detects exactly one CLI-owned profile (client: "cli" or the exact legacy cli@<workspace> shape) and makes that existing profile active. When several profiles are stored, passport profiles lists them and passport use <name> changes the local active profile without contacting Passport. If more than one CLI candidate remains, Passport refuses to guess and asks for an explicit selector. Scripts should use an explicit selector so they cannot accidentally run against another workspace.

passport profiles
passport use cli@work
passport status --profile cli@work
passport search "issues" --profile cli@work

To keep app selection and Activity distinct for a specific terminal agent, create a per-agent profile:

passport login \
  --cloud https://passportmcp.com \
  --workspace <workspace-id> \
  --client claude-code \
  --profile claude-code@work

PASSPORT_PROFILE=claude-code@work passport search "issues"
passport status --profile claude-code@work

Passport can also add cooperative caller detail from known agent environment variables. --caller <id> takes precedence. Activity labels it as self-reported, for example Passport CLI · Codex via CLI; the authenticated member or agent and the policy agent remain separate identities. OpenCode is a first-class policy identity too, but it is not listed in the Add agent hub — set it up with the CLI. Use --client opencode --profile opencode@work when its selection and Activity should remain distinct from other terminal agents.

Headless, CI, and cron

For scripts and CI, create an automation key in Agents → Automations, then inject it and the workspace endpoint through your CI secret store. Environment-key mode works without passport login and writes no local credential file.

export PASSPORT_AGENT_KEY='<agent-key>'
# Must be the workspace MCP URL (/w/ws_…/mcp), same shape as hosted connectors.
export PASSPORT_ENDPOINT='https://passportmcp.com/w/ws_…/mcp'

passport status --json
passport search "failed builds" --json
passport run sentry_list_issues '{"status":"unresolved"}' --json
passport version --json
passport ready --json

Agent keys can inspect status and call allowed tools, but cannot mint a person’s sign-in link. Use passport connect from an interactive member profile when an app needs personal OAuth. Legacy agent keys are non-interactive: they do not create action-time member approval prompts. Use a member profile for an operation that must pause for a human’s one-off approval.

The CLI never wraps provider APIs directly and never bypasses the gateway. It calls Passport’s governed meta-tools and MCP resource/prompt methods, so CLI and MCP usage share one policy and audit pipeline.

Start here

Using Passport

Manage a workspace

Enterprise security

Self-hosting

Technical reference

Commands

Diagnose and complete

JSON and exit-code contract

Profiles and attribution

Headless, CI, and cron

​Install and sign in

​Commands

​Diagnose and complete

​JSON and exit-code contract

​Profiles and attribution

​Headless, CI, and cron

Install and sign in

Commands

Diagnose and complete

JSON and exit-code contract

Profiles and attribution

Headless, CI, and cron