# Provon CLI

The Provon CLI provides command-line access to project context, traces, local diagnosis, Findings,
Knowledge, transcript sync, and self-hosted models.

Use the CLI for repeatable investigation and automation. Use the Workbench for interactive review
and project administration.

## Build From The Repository

The CLI requires Node.js 22 or later:

```bash
pnpm install
pnpm --filter @provon/cli build
node cli/dist/bin.js --help
```

During repository development, replace `provon` in the examples with `node cli/dist/bin.js`.

## Authenticate

For an interactive user session:

```bash
provon auth login
provon workspace projects list
provon project use <project-id>
```

For service automation with a project API key:

```bash
provon auth token set \
  --api-key "$PROVON_API_KEY" \
  --project "$PROVON_PROJECT_ID"
```

Flags and environment variables override the active local profile. See
[CLI authentication](./authentication.md).

## Commands By Task

| Task                                  | Command group    | Guide                                 |
| ------------------------------------- | ---------------- | ------------------------------------- |
| Configure authentication and origins  | `auth`, `config` | [Authentication](./authentication.md) |
| Manage organizations and projects     | `workspace`      | [Workspace](./workspace.md)           |
| Select a project                      | `project`        | [Authentication](./authentication.md) |
| Manage project API keys               | `api-keys`       | [API keys](./api-keys.md)             |
| Query and export traces               | `traces`         | [Tracing CLI](./traces.md)            |
| Inspect local agent transcripts       | `transcripts`    | [Transcripts CLI](./transcripts.md)   |
| Upload persisted transcripts          | `sync`           | [Sync CLI](./sync.md)                 |
| Diagnose local evidence               | `diagnose`       | [CLI diagnosis](./diagnose.md)        |
| Review and hand off Findings          | `findings`       | [Findings CLI](./findings.md)         |
| Materialize project Knowledge         | `knowledge`      | [Knowledge CLI](./knowledge.md)       |
| Manage project datasets               | `datasets`       | [Datasets CLI](./datasets.md)         |
| Manage AI Gateway providers           | `gateway`        | [Gateway CLI](./gateway.md)           |
| Manage project connector integrations | `connectors`     | [Connectors CLI](./connectors.md)     |
| Install and serve local models        | `models`         | [Models CLI](./models.md)             |

## Output Contract

Commands emit machine-readable JSON envelopes by default. Successful responses contain the command
result and can include suggested next actions. Failures contain a stable error code, message,
retryability flag, and optional details.

Use exit status as the primary automation signal. Do not parse human descriptions as a stable API.

## Global Options

```text
--api-key <key>    Override PROVON_API_KEY
--project <id>     Override PROVON_PROJECT_ID
--profile <name>   Select a local authentication profile
--version          Print the CLI version
```

Run `provon help <command>` for the options supported by the installed version.