# What does the provely CLI do?

> provely is one static binary: verify and status drive an operation, receipt validate checks a receipt offline, and mcp serves the tools over stdio.

Canonical: https://provely.sh/docs/cli  
Last reviewed: 2026-09-05  

**`provely` is one static binary for Linux, macOS, and Windows. It drives an operation from scripts and CI, validates receipts offline, and serves the MCP tools over stdio.**

*Install*

```text
# Run without an install
npx provely --version

# Or download the static binary for your platform and put it on PATH
provely --version
```

The CLI is a client of the control plane. It contains no verification logic.

## Which commands exist?

| Command | Purpose |
| --- | --- |
| `provely scan <path>` | Parse TypeScript and JavaScript, find side-effecting calls, and name the contract that would verify each one. Runs locally. Sends nothing. |
| `provely begin <contract> --input <json>` | Open an operation. Print the operation id and the idempotency key. |
| `provely action-result <operation_id> --file <json>` | Submit the provider acknowledgement. |
| `provely verify <operation_id> [--wait <duration>]` | Verify once, or poll until a terminal verdict or the deadline. |
| `provely status <operation_id>` | Resume any prior operation. |
| `provely receipt validate <file>` | Validate a receipt offline against your trusted key map. |
| `provely skill generate <provider\|--openapi <url>>` | Call the hosted compiler and write the review bundle. |
| `provely init --agent <name>` | Write the guidance files for an agent target from its integration profile. |
| `provely mcp` | Serve begin, verify, status, and receipt over stdio. |

## Which exit codes does the CLI use?

| Exit code | Meaning |
| --- | --- |
| 0 | VERIFIED, or a command with no verdict succeeded |
| 1 | Error, invalid receipt, or a scan with findings |
| 2 | PENDING |
| 3 | FAILED |
| 4 | CONTRADICTED |
| 5 | UNVERIFIABLE |

> A usage error exits 1, not 2. The code 2 belongs to PENDING. A CI gate must not read a typo as "not done yet".

## How do I gate a pipeline on a verdict?

*A CI step*

```yaml
- name: Verify the refund reached succeeded
  run: provely verify "$OPERATION_ID" --wait 10m --json
  # exit 0 only on VERIFIED; PENDING exits 2 and fails the step
```

## How do I validate a receipt offline?

### Validate a receipt with the CLI

1. **Install the CLI.** Download the `provely` static binary for Linux, macOS, or Windows, or run `npx provely`.
2. **Put the trusted keys in the configuration.** The validator needs a key map that you control. It maps a key id to a public key. A receipt that verifies against its own embedded key proves nothing.
3. **Run the validator.** Run `provely receipt validate receipt.json`. The exit code is the verdict code: 0 VERIFIED, 2 PENDING, 3 FAILED, 4 CONTRADICTED, 5 UNVERIFIABLE. An invalid receipt gives 1.
4. **Gate on the exit code.** A pipeline step passes only on a valid VERIFIED receipt. A valid PENDING receipt is not done.

### Does the scanner send my code anywhere?

No. It parses the files locally and prints a report. It makes no network call.

### Where does the CLI read the API key?

From its configuration file or the `PROVELY_API_KEY` environment variable. There is no `--api-key` flag, so a key never lands in a shell history or a process list.

## Read next

- [Read the MCP server reference](https://provely.sh/docs/mcp)
- [Read how to validate a receipt](https://provely.sh/receipts)
- [See every agent integration](https://provely.sh/agents)