Passport CLI

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 client 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. No desktop app required.

Windows (PowerShell)
Linux
macOS

npm install --global passport-bridge
passport version
passport login --workspace <workspace-id> --profile cli@<workspace-id>
passport status
passport search ""

npm install --global passport-bridge
passport version
passport login --workspace <workspace-id> --profile cli@<workspace-id>
passport status
passport search ""

npm install --global passport-bridge
passport version
passport login --workspace <workspace-id> --profile cli@<workspace-id>
passport status
passport search ""

Passport Desktop is optional if you want to wire several local GUI clients at once.

Install once

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

npm i -g passport-bridge
passport version

Copy the workspace id (ws_…) from your Passport browser URL or from the connector URL under Clients → Add client (/w/ws_…/mcp). Login opens a browser and stores the resulting refresh credential in the existing ~/.passport/credentials.json profile store with owner-only permissions. A successful login activates the profile it creates.

passport login --workspace ws_… --profile cli@ws_…
passport status
passport doctor

Passport Cloud is the default when --workspace is provided. Self-hosted deployments also pass --cloud <origin>. On SSH, CI, or another headless host, add --no-open so Passport prints the verification URL instead of trying to launch a browser:

passport login --workspace ws_… --profile cli@ws_… --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 client, and visible MCP 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 the cross-platform managed scanner for Passport Discover. 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 Find connections outside Passport.

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, client 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 client. 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 client remain separate identities. OpenCode is a first-class policy identity too, but it is not listed in the Add client 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

Create an agent identity and key in Settings (Advanced → Headless & CI on Free/Pro; the Headless & CI card on Enterprise), then inject both variables through your CI secret store. Environment-key mode wins over local profiles, writes nothing to disk, and works without passport login.

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. Agent keys are also 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