Skip to content

Ingest CLI

provon ingest gets agent sessions into Provon as OTLP traces. It covers two complementary paths:

View as Markdown Open the plain-text version of this page.
  • Live capture (provon ingest hooks install) — install hooks into AI coding tools so sessions are reported as they happen.
  • Backfill sync (provon ingest sync) — scan persisted transcript directories and upload them as traces.
Live capture Backfill sync OTLP /v1/traces Workbench Traces Tool hook event Detached reporter Transcript directory scan OTLP projection

Prerequisites#

  • A selected project id and reporting credential (see Authentication).
  • For live hooks: the target coding tool installed so detection passes (use --skip-check to force installation anyway).
  • For sync: a directory containing supported transcript files.

Quick Start#

bash
# Live: install hooks for all detected tools
provon --project <project-id> --api-key <key> ingest hooks install

# Backfill: one pass over an existing transcript directory
provon ingest sync ~/.claude/projects --once

Commands#

Command Description
provon ingest hooks install Install live trace hooks into detected AI coding tools
provon ingest hooks uninstall Remove Provon hook entries and generated plugins
provon ingest sync <path> Backfill one transcript directory, or watch it continuously
provon ingest trace Internal runtime entry invoked by installed hooks; not for manual use

Live Capture vs Backfill Sync#

Live capture (hooks) Backfill sync (sync)
Trigger Agent hook events (tool start/stop) Directory scan or watcher
Latency Real-time, non-blocking reporter Batch, on-demand
Best for Ongoing sessions Existing local transcripts
State Hook entries in tool config files Local state store with content hashes
Idempotent Yes; re-running updates existing entries Yes; unchanged files are skipped

Sync state is stored under ~/.local/state/provon/sync/ (override with XDG_STATE_HOME or PROVON_SYNC_STATE_DIR), keyed by transcript path, API URL, and project id.

Supported Transcript Formats#

sync parses Claude Code JSONL (~/.claude/projects), Codex session JSONL (~/.codex/sessions), and Pi session files (~/.pi/agent/sessions). Pass any directory path explicitly; the parser detects the format from file content. Live hooks cover the wired coding tools listed in Install Hooks.

Success Check#

  • Live: after installing, run one agent turn and open the project's Traces view; a new conversation should appear within the hook's reporting delay.
  • Sync: provon ingest sync <path> --once returns ok: true with scanned/processed counts; repeat it and confirm processed counts drop to zero (state-aware skip).

Troubleshooting#

Symptom Likely cause Fix
MISSING_PROJECT_ID on hooks install No project in profile or flags provon project use <id>, or pass --project <id>
Hooks install succeeds but nothing reports Plugin target currently inactive in this build (see page note) Use sync backfill for that tool, or check PROVON_TRACE_DEBUG=1 output
sync uploads nothing every run State file key mismatch after changing project/API URL State keys on path + API URL + project; rerun against the same target
Upload payload rejected Tool output too large Lower --include-tool-output or --max-payload-bytes
Watch mode exits immediately SIGINT/SIGTERM received Re-run without --once in a persistent terminal

Sub-pages#

  • Install Hooks CLI — full reference for provon ingest hooks install/uninstall
  • Sync CLI — full reference for provon ingest sync