---
title: Pathwright CLI and local MCP
description: Install the Pathwright CLI, connect it to a Learning Space, and author through the CLI, local MCP, or SDK scripts.
source: npm
original: https://www.npmjs.com/package/@pathwright/cli/v/0.1.0-preview.3
retrieved: 2026-11-09
visibility: public
version: 0.1.0-preview.3
---

# Pathwright CLI and local MCP

Requires Node.js 22 or newer. This is a preview release for authoring against an enabled Pathwright Learning Space.

## Install

```sh
npm install -g @pathwright/cli@preview
pathwright --version
```

For a repeatable installation, pin this release:

```sh
npm install -g @pathwright/cli@0.1.0-preview.3
```

The `preview` tag follows preview releases. Preview interfaces may change; pin a version for automated workflows. This package requires an enabled Learning Space with compatible backend services. Installing it does not enable server features. The reviewed Cohort customization/revert operations require the matching backend lifecycle support; they may not yet be deployed to your Space.

## Connect through your agent

Configure local MCP first; you do not need to run a terminal login:

```json
{"mcpServers":{"pathwright-staging":{"command":"pathwright","args":["--profile","staging","mcp"]}}}
```

Ask your agent to connect to `https://paths.pathwrightstaging.com`. It calls
`connection_status`, then `connection_start` if signed out, and opens the returned
`approvalUrl` visibly in its browser. Sign in and approve the connection yourself.
The agent checks `connection_status` and uses that same browser for live previews.
The browser and local MCP server must run on the same computer.

A saved connection is reused automatically. `connection_start` with `reconnect: true`
starts a replacement approval if it has expired or been revoked. A profile cannot
silently switch Spaces; choose a different profile or log out first.

For a terminal-capable agent without MCP:

```sh
pathwright --profile staging login --space https://paths.pathwrightstaging.com --no-browser --json
```

Keep that process running. It emits a `pending` JSON line with `approvalUrl`, then a
`connected` JSON line when approval succeeds. The agent opens the URL with its own
browser tool. For manual login, omit `--no-browser --json` to open your default browser.

Named profiles keep connections separate. Use the same profile in commands, MCP
configuration, and local SDK scripts. Approval uses your current Space permissions;
no passwords or tokens need to be copied into your agent.

## Live preview

Browser sign-in is separate from the CLI connection. If the preview opens in a browser you have not signed into—including your agent’s browser—sign in to the same Learning Space with an account that can edit the content. You should return to the preview after sign-in.

```sh
pathwright --profile staging preview --path PATH_ID --step STEP_ID --open
```

Use IDs from `paths list` and `paths get`. The command checks the target and resolves its Source Step URL. Omit `--open` to print the link only; add `--json` for structured output. Keep the browser tab visible while authoring. Preview is read-only and does not publish.

## Local MCP

Configure your MCP host to launch:

```json
{"mcpServers":{"pathwright-staging":{"command":"pathwright","args":["--profile","staging","mcp"]}}}
```

If your desktop host cannot find the global executable, use its absolute path. Use MCP connection_start when signed out; a separate CLI login is optional. Do not copy tokens into MCP configuration. Tool discovery works while signed out. The `preview_get` tool returns a live-preview URL for a browser-capable agent to open visibly.

## Local SDK scripts

```ts
import { connectSaved } from "@pathwright/cli/node"

const client = await connectSaved({ profile: "staging" })
const cohorts = await client.cohorts.list({ resourceId: 17714 })
```

This Node-only helper uses the saved CLI/MCP profile, renews it automatically, and
checks the connected identity. It never opens a browser implicitly. Connect through
your agent or CLI first. Hosted applications need their own credential lifecycle.

## Authoring

Create a new test Path without any repository scripts:

```sh
pathwright --profile staging paths create "My agent test" --json
pathwright --profile staging lessons create "Start here" --path PATH_ID --json
pathwright --profile staging steps create "Welcome" --path PATH_ID --lesson LESSON_ID --json
```

MCP provides `paths_create`, `lessons_create`, and `steps_create` for the same workflow. Use `content_append` for the first mixed-Block content on an empty Step.

Discover commands with `pathwright commands --json` and inspect an operation's `--schema` before writing. Read and review current revisions before edits. Reconcile uncertain writes by reading the target or append receipt; never blindly retry. Publishing remains a deliberate action through the existing Pathwright UI. New media upload is not included.

Use `pathwright --profile staging logout` to revoke the connection. Credentials are stored outside the repository under the selected profile in the user's config directory. `PATHWRIGHT_CONFIG_DIR` overrides the base directory.

## License

This CLI/SDK package is licensed under the [MIT License](https://unpkg.com/@pathwright/cli@0.1.0-preview.3/LICENSE). This license applies to this package only; it does not relicense the rest of Pathwright's codebase or hosted service.