Ingest Sync CLI

Use provon ingest sync to upload persisted agent transcript directories to Provon as OTLP traces. It complements live hooks for historical or on-demand backfill; see Ingest overview for the two-path comparison.

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

Prerequisites#

A project credential with telemetry:ingest (profile, --api-key, or PROVON_API_KEY).
A transcript directory readable by the current user.
Supported transcript formats: Claude Code JSONL, Codex session JSONL, Pi JSONL/JSON.

Sync Once#

Run a single backfill pass and exit:

provon ingest sync ~/.claude/projects --once

Common default locations (override with any explicit path):

~/.claude/projects
~/.codex/sessions
~/.pi/agent/sessions

Watch Mode#

Run continuously and rescan for new or changed files:

provon ingest sync ~/.claude/projects

The watcher exits on SIGINT or SIGTERM; it reports a summary after each scan pass that finds changes, failures, or an empty directory.

Dry Run#

Parse and summarize changes without uploading or writing state:

provon ingest sync ~/.claude/projects --once --dry-run

Add --print-sample to include a small OTLP payload sample in the JSON output for inspection.

Tool Output Handling#

Control how tool outputs appear in uploaded spans:

provon ingest sync ~/.claude/projects --once --include-tool-output full

Modes: truncated (default), none, full.

Options#

--once                      Run one backfill pass and exit
--dry-run                   Parse and summarize changes without uploading or updating state
--print-sample              Include a small OTLP payload sample in the JSON output
--include-tool-output <m>   truncated (default), none, or full
--poll-interval <ms>        Watch-mode rescan interval (default 30000)
--settle-ms <ms>            Watch-mode debounce interval (default 1000)
--max-payload-bytes <n>     Maximum bytes per OTLP upload payload (default 8388608)

State Store#

Sync remembers processed files with content hashes. State files live under ~/.local/state/provon/sync/, keyed by transcript path, API URL, and project id; override the root with XDG_STATE_HOME or PROVON_SYNC_STATE_DIR. Changing the target project or API URL starts a fresh state key, so files are reprocessed against the new target.

Success Check#

provon ingest sync ~/.claude/projects --once

The response reports scannedFiles, changedFiles, uploadedFiles, and failures. Re-run the same command: changedFiles should drop to zero and failures should be empty. Confirm traces in the Workbench Traces view or with provon traces list.

Troubleshooting#

Symptom	Likely cause	Fix
`auth.missing_credential`	No credential resolved	`provon auth token set` or export `PROVON_API_KEY`
`MISSING_PROJECT_ID`	No project context	`provon project use <id>` or export `PROVON_PROJECT_ID`
`scannedFiles: 0`	Wrong directory or unsupported format	Pass the exact transcript dir; verify a sample file parses with `--dry-run --print-sample`
Repeated uploads of the same files	State key changed (project/URL/path)	Keep the same target; inspect `statePath` in the response
Upload failures listed per file	Network or payload-size issue	Check `failures[].message`; reduce `--max-payload-bytes` or `--include-tool-output`
Watch mode stops after terminal close	Foreground process tied to the shell	Run in a persistent terminal or `tmux`/`screen` session