# Passport CLI

Paste this to a terminal agent: Install and use Passport CLI from https://passportmcp.com/connect/cli

## For the agent

Use Passport's governed gateway from any terminal or headless agent. This page is public and holds no secrets.

1. Install the Passport CLI. The package also contains the local MCP bridge; this command installs both binaries:

   ```
   npm i -g passport-bridge
   ```
2. Sign in once for this machine. The browser confirms your Passport identity; no credential is written into an AI client config:

   ```
   passport login --cloud https://passportmcp.com --workspace <workspace-id>
   ```
3. Discover a namespaced tool, inspect its schema, then run it. The name returned by search can be passed directly to describe or run:

   ```
   passport status
   passport search "issues"
   passport describe github_search_issues
   passport run github_search_issues '{"query":"SSO"}'
   ```
4. If a tool needs a personal account, ask Passport for the governed connection flow. Add --open to open the sign-in page and --wait to wait for completion:

   ```
   passport connect github --open --wait 120
   ```
5. Stop there. Setup is complete.


## Choose the right door

Use Passport CLI for Claude Code, Codex CLI, OpenCode, shell scripts, CI, and cron. Keep native MCP for GUI and hosted clients such as Cursor chat, VS Code chat, Claude Desktop, claude.ai, and ChatGPT. Both routes execute through the same governed gateway.

## Commands

- `status`: workspace, profile, visible MCPs, connection state, and permitted tool counts.
- `doctor`: diagnose runtime, credential-store safety, endpoint reachability, authentication, and CLI protocol compatibility without printing secrets.
- `search [query]` / `describe <tool>`: discover namespaced tools and inspect schemas.
- `run <tool> [json-args]`: execute through policy, approvals, guardrails, selection, and audit.
- `connect [app...]`: start or wait for a governed personal-account connection.
- `resources [uri]` / `prompts [name]`: use workspace MCP resources and prompts.
- `completion <bash|zsh|fish>`: generate local shell completion without a profile or network request.
- `login` / `logout` / `help` / `version`: manage profiles and inspect the CLI.

## Machine-readable output

`--json` writes exactly one JSON value to stdout. Hints and warnings go to stderr. JSON errors contain `error`, `cause`, and `exitCode`, plus `approvalId` or `app` when relevant.

```sh
passport search "issues" --json | jq '.results[].tool'
passport run github_search_issues --args - --json < input.json
```

## Exit codes

| Code | Meaning |
| ---: | --- |
| 0 | Success |
| 1 | Network, server, or ambiguous execution error. Do not retry automatically. |
| 2 | Authentication required. Run passport login. |
| 3 | The app needs a connection. Run passport connect <app>. |
| 4 | Approval is pending. The response includes the approval id. |
| 5 | Blocked by policy, a guardrail, client selection, or approval denial. |
| 6 | Usage error or unknown tool. |

## Profiles and caller attribution

The default policy identity is `cli`. A per-agent profile keeps selection and audit distinct. The optional caller label adds cooperative detail such as “Codex via CLI”; it is self-reported, not a second authenticated identity.

```sh
passport login --cloud https://passportmcp.com --workspace <workspace-id> --client claude-code --profile claude-code@workspace
PASSPORT_PROFILE=claude-code@workspace passport search "issues"
passport run github_search_issues '{"query":"SSO"}' --caller claude-code
```

## Headless and CI

Create a governed agent identity and key in Passport, inject these variables through your CI secret store, and run without a local profile. Nothing is persisted. Agent keys can call tools but cannot create a person's sign-in link or raise an interactive member approval; their assigned pass, selection, guardrails, middleware, and audit trail still apply.

```sh
export PASSPORT_AGENT_KEY='<agent-key>'
export PASSPORT_ENDPOINT='https://passportmcp.com/w/<workspace-id>/mcp'
passport status --json
passport search "failed builds" --json
passport run sentry_list_issues '{"status":"unresolved"}' --json
```


## Rules

- Use the namespaced tool name returned by search. Do not translate it into another identifier.
- Use --json for machine-readable output. In JSON mode stdout is exactly one JSON value; hints and warnings go to stderr.
- Treat exit code 4 as approval pending, not failure. Retry only with --wait; never retry an ambiguous network timeout.
- The CLI and MCP connector use the same gateway pipeline. Member profiles share policy, approvals, guardrails, app selection, and audit; non-interactive agent keys use their assigned pass and guardrails without a member approval prompt.