provardx-cli

# @provartesting/provardx-cli

[![Version](https://img.shields.io/npm/v/@provartesting/provardx-cli.svg)](https://npmjs.org/package/@provartesting/provardx-cli)
[![Downloads/week](https://img.shields.io/npm/dw/@provartesting/provardx-cli.svg)](https://npmjs.org/package/@provartesting/provardx-cli)
[![License](https://img.shields.io/npm/l/@provartesting/provardx-cli.svg)](https://github.com/ProvarTesting/provardx-cli/blob/main/LICENSE.md)
[![Get Access](https://img.shields.io/badge/Quality%20Hub%20API-Get%20Access-blue)](https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access)

# What is the ProvarDX CLI?

The Provar DX CLI is a Salesforce CLI plugin for Provar customers who want to automate the execution of tests using Provar Automation, and the reporting of test results and other quality-related metrics to Provar Quality Hub.

# Installation, Update, and Uninstall

**Requires Node.js 18–24 (LTS 22 recommended).** Node 25+ is not yet supported due to a breaking change in a transitive dependency. Check with `node --version`.

Install the plugin

```sh-session
$ sf plugins install @provartesting/provardx-cli
```

Update plugins

```sh-session
$ sf plugins update
```

Uninstall the plugin

```sh-session
$ sf plugins uninstall @provartesting/provardx-cli
```

# MCP Server (AI-Assisted Quality)

The Provar DX CLI includes a built-in **Model Context Protocol (MCP) server** that connects AI assistants (Claude Desktop, Claude Code, Cursor) directly to your Provar project. Once connected, an AI agent can inspect your project structure, generate Page Objects and test cases, validate every level of the test hierarchy with quality scores, and work with NitroX (Hybrid Model) component page objects for LWC, Screen Flow, Industry Components, Experience Cloud, and HTML5.

Validation runs in two modes: **local only** (structural rules, no key required) or **Quality Hub API** (170+ rules, quality scoring — requires a `pv_k_` API key). Don't have an account? **[Request access](https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access)**.

## Quick setup

**Requires:** Provar Automation IDE installed with an activated license. Node.js 18–24 must be on your PATH.

### Option A — Zero-install (recommended for Claude Desktop)

No prior setup needed. Paste this into your Claude Desktop config file and restart the app:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "provar": {
      "command": "npx",
      "args": ["-y", "@provartesting/provardx-cli", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
    }
  }
}
```

`npx -y` downloads the package automatically on first use — no `sf` or separate install step required.

**Claude Code** — run once to register the server:

```sh
claude mcp add provar -s user -- npx -y @provartesting/provardx-cli mcp start --allowed-paths /path/to/your/provar/project
```

### Option B — Global sf plugin install

Prefer a persistent global install? Install once, then use the `sf` command:

```sh
# 1. Install the plugin
sf plugins install @provartesting/provardx-cli

# 2. (Optional) Authenticate for full 170+ rule validation
sf provar auth login
```

**Claude Desktop** config using the global install:

```json
{
  "mcpServers": {
    "provar": {
      "command": "sf",
      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
    }
  }
}
```

> **Windows (Claude Desktop):** Use `sf.cmd` instead of `sf` if the server fails to start.

**Claude Code** using the global install:

```sh
claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
```

📖 **[docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) — full setup, all 43 tools, 6 resources, 11 MCP prompts, troubleshooting.**

---

# Commands

- [`sf provar auth login`](#sf-provar-auth-login)
- [`sf provar auth rotate`](#sf-provar-auth-rotate)
- [`sf provar auth status`](#sf-provar-auth-status)
- [`sf provar auth clear`](#sf-provar-auth-clear)
- [`sf provar mcp start`](#sf-provar-mcp-start)
- [`sf provar config get`](#sf-provar-config-get)
- [`sf provar config set`](#sf-provar-config-set)
- [`sf provar automation config generate`](#sf-provar-automation-config-generate)
- [`sf provar automation config load`](#sf-provar-automation-config-load)
- [`sf provar automation config validate`](#sf-provar-automation-config-validate)
- [`sf provar automation config get`](#sf-provar-automation-config-get)
- [`sf provar automation config set`](#sf-provar-automation-config-set)
- [`sf provar automation setup`](#sf-provar-automation-setup)
- [`sf provar automation project compile`](#sf-provar-automation-project-compile)
- [`sf provar automation metadata download`](#sf-provar-automation-metadata-download)
- [`sf provar automation test run`](#sf-provar-automation-test-run)
- [`sf provar quality-hub connect`](#sf-provar-quality-hub-connect)
- [`sf provar quality-hub display`](#sf-provar-quality-hub-display)
- [`sf provar quality-hub open`](#sf-provar-quality-hub-open)
- [`sf provar quality-hub testcase retrieve`](#sf-provar-quality-hub-testcase-retrieve)
- [`sf provar quality-hub test run`](#sf-provar-quality-hub-test-run)
- [`sf provar quality-hub test run report`](#sf-provar-quality-hub-test-run-report)
- [`sf provar quality-hub test run abort`](#sf-provar-quality-hub-test-run-abort)
- [`sf provar manager connect`](#sf-provar-manager-connect) _(deprecated — use `sf provar quality-hub connect`)_
- [`sf provar manager display`](#sf-provar-manager-display) _(deprecated — use `sf provar quality-hub display`)_
- [`sf provar manager open`](#sf-provar-manager-open) _(deprecated — use `sf provar quality-hub open`)_
- [`sf provar manager testcase retrieve`](#sf-provar-manager-testcase-retrieve) _(deprecated — use `sf provar quality-hub testcase retrieve`)_
- [`sf provar manager test run`](#sf-provar-manager-test-run) _(deprecated — use `sf provar quality-hub test run`)_
- [`sf provar manager test run report`](#sf-provar-manager-test-run-report) _(deprecated — use `sf provar quality-hub test run report`)_
- [`sf provar manager test run abort`](#sf-provar-manager-test-run-abort) _(deprecated — use `sf provar quality-hub test run abort`)_

## `sf provar auth login`

Log in to Provar Quality Hub and store your API key.

```
USAGE
  $ sf provar auth login [--url <value>]

FLAGS
  --url=<value>  Override the Quality Hub API base URL (for non-production environments).

DESCRIPTION
  Opens a browser to the Provar login page. After you authenticate, your API key is
  stored at ~/.provar/credentials.json and used automatically by the Provar MCP tools
  and CI/CD integrations. The key is valid for approximately 90 days.

  For CI/CD pipelines (GitHub Actions, Jenkins, etc.) where a browser cannot open:
  run sf provar auth login once on your local machine, copy the api_key value from
  ~/.provar/credentials.json, and store it as the PROVAR_API_KEY environment variable
  or secret in your pipeline. Rotate the secret every ~90 days when the key expires.

  Don't have an account? Request access at:
  https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access

EXAMPLES
  Log in interactively:

    $ sf provar auth login

  Log in against a staging environment:

    $ sf provar auth login --url https://dev.api.example.com
```

## `sf provar auth rotate`

Rotate your stored API key without re-authenticating via browser.

```
USAGE
  $ sf provar auth rotate

DESCRIPTION
  Exchanges your current pv_k_ key for a new one atomically. The old key is
  invalidated immediately. The new key is written to ~/.provar/credentials.json.

  Use this to rotate your key on a regular schedule (~every 90 days) without
  going through the browser login flow. If your current key is already expired,
  run sf provar auth login instead.

EXAMPLES
  Rotate the stored API key:

    $ sf provar auth rotate
```

## `sf provar auth status`

Show the current API key configuration and validate it against Quality Hub.

```
USAGE
  $ sf provar auth status

DESCRIPTION
  Reports whether an API key is configured, where it came from (environment variable
  or credentials file), and performs a live check against the Quality Hub API to
  confirm the key is still valid.

EXAMPLES
  Check auth status:

    $ sf provar auth status
```

## `sf provar auth clear`

Remove the stored API key.

```
USAGE
  $ sf provar auth clear

DESCRIPTION
  Deletes ~/.provar/credentials.json and revokes the key server-side. After clearing,
  the MCP tools fall back to local validation mode. Has no effect if no key is stored.

EXAMPLES
  Remove the stored key:

    $ sf provar auth clear
```

## `sf provar mcp start`

Start a local MCP server for Provar tools over stdio transport.

```
USAGE
  $ sf provar mcp start [-a <value>...]

FLAGS
  -a, --allowed-paths=<value>...  Allowed base directory paths for file operations.
                                  Defaults to the current working directory.
                                  Repeat the flag to allow multiple paths.

DESCRIPTION
  Launches a stateless MCP (Model Context Protocol) server that exposes Provar tools
  to AI assistants (Claude Desktop, Claude Code, Cursor) via stdio transport. All MCP
  JSON-RPC communication happens over stdout; all internal logging goes to stderr.

  Note: --json is not available on this command — stdout is reserved for MCP traffic.

TOOLS EXPOSED
  43 tools across: project inspection & org describe, Page Object and test-case
  authoring/validation, test-suite/plan validation, properties files, Quality Hub
  (test runs, defects, corpus examples), Provar Automation, ANT build, and NitroX
  components. See docs/mcp.md for the full catalogue with schemas and examples.

EXAMPLES
  Start MCP server (accepts stdio connections from Claude Desktop / Cursor):

    $ sf provar mcp start