Skip to content

Provon CLI

The Provon CLI provides command-line access to project context, traces, local diagnosis, Findings, live capture hooks, and transcript backfill sync. Use it for repeatable investigation and automation; use the Workbench for interactive review and project administration.

View as Markdown Open the plain-text version of this page.

First Successful Workflow#

Prerequisites#

  • The provon CLI binary on PATH (see Install Provon).
  • A Provon project id, and either a browser session or a project API key.

Steps#

bash
# 1. Authenticate (interactive browser flow)
provon auth login

# 2. List available projects and select one
provon workspace projects list
provon project use <project-id>

# 3. Confirm the active configuration
provon auth status

# 4. Query recent traces
provon traces list

Success Check#

provon auth status reports authenticated: true and the selected project id; provon traces list returns a JSON envelope with ok: true and a data array.

For service automation, store a project API key instead of a browser session:

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

Commands By Task#

Task Command group Guide
Configure authentication and origins auth, config Authentication
Browse organizations and projects workspace Workspace
Select the active project project Authentication
Manage project API keys and usage policies api-keys API keys
Query, summarize, and export traces traces Traces
Install live capture hooks into AI coding tools ingest hooks Install hooks
Backfill persisted transcript directories ingest sync Ingest sync
Diagnose local evidence against diagnostic Rules diagnose Diagnose
Review Findings and create work items findings Findings
Manage AI Gateway providers, routing, and guardrails gateway Gateway
Manage connector integrations connectors Connectors
Govern MCP servers, tools, credentials, and policies mcp MCP

Global Options#

text
--api-key <key>   Project API key override (env: PROVON_API_KEY)
--project <id>    Project id override for workspace-scoped routes (env: PROVON_PROJECT_ID)
--profile <name>  Local authentication profile name (env: PROVON_PROFILE)
--version         Print the CLI version

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

Output Contract#

Commands emit a JSON envelope on stdout. Success envelopes are { ok: true, data, warnings, nextActions }; failure envelopes are { ok: false, error: { code, message, retryable, details } } printed on stderr. Use the exit status and ok field as the automation signal; do not parse human-readable messages as a stable API.

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.

Troubleshooting#

Common error codes and fixes:

Error code Meaning Fix
auth.missing_credential No credential resolved Run provon auth login or provon auth token set
auth.session_expired Browser session refresh failed Run provon auth login again
MISSING_PROJECT_ID No active project for the command provon project use <id> or pass --project <id>
TARGET_CONFLICT Hooks already report another project Re-run with --append, or uninstall the existing target
HTTP_401 / HTTP_403 Credential missing a required capability Issue a key with the capability listed in API keys