# Ingest CLI

`provon ingest` is the unified command group for getting agent sessions into Provon as OTel traces. It covers two complementary paths:

- **Live capture** (`provon ingest hooks install`) — install hooks into AI coding tools so sessions are reported in real time as they happen.
- **Backfill sync** (`provon ingest sync`) — scan persisted transcript directories and upload them as traces.

Both paths share the same transcript parsing, OTel projection, and upload pipeline.

## Quick start

```bash
# Live: install hooks for all detected tools (Claude, Codex, OpenCode, dsh, Cursor, Pi)
# Credentials from global flags or `provon auth login`
provon --project <project-id> --api-key <key> ingest hooks install

# Backfill: one-time upload of existing transcripts
provon ingest sync ~/.claude/projects --once
```

## Commands

| Command                         | Description                                   |
| ------------------------------- | --------------------------------------------- |
| `provon ingest hooks install`   | Install live trace hooks into AI coding tools |
| `provon ingest hooks uninstall` | Remove all Provon trace hooks                 |
| `provon ingest sync <path>`     | Backfill (or watch) a transcript directory    |
| `provon ingest trace`           | Internal runtime entry invoked by hooks       |

## Live capture vs backfill sync

|            | Live capture (`hooks`)                  | Backfill sync (`sync`)               |
| ---------- | --------------------------------------- | ------------------------------------ |
| Trigger    | Agent hook events (session start/stop)  | Directory scan                       |
| Latency    | Real-time, non-blocking                 | Batch, on-demand                     |
| Best for   | Ongoing sessions                        | Historical transcripts, migrations   |
| State      | Hook entries in tool configs            | Local state file with content hashes |
| Idempotent | Yes (re-running updates existing hooks) | Yes (unchanged files are skipped)    |

## Sub-pages

- [Install Hooks CLI](./install-hooks.md) — full reference for `provon ingest hooks install/uninstall`
- [Sync CLI](./sync.md) — full reference for `provon ingest sync`