First-run events

The hook reports one of three event types. Two of them are conversions, counted once per installation.

Event	Report it	Counted
`install_completed`	After every installation step succeeded.	Once per installation ID. The default.
`first_run`	From your CLI's entry point, on launch.	Once per installation ID.
`install_started`	Before installing, to measure attempts.	Once per installation ID. Not a conversion: only webhooks receive it.

#Installation IDs

On its first run, the hook creates a random 128-bit installation ID and keeps it in <state dir>/<service>/<website>/<scope>.id, where the state dir defaults to ~/.local/state/clitrail. Later reports from the same user, website and scope reuse it, so launching your CLI a hundred times still produces one first_run. Updating the hook you bundle keeps existing IDs: in the default folder, a hook with no ID yet reuses the one an older copy kept under ~/.local/state/opfs-attribution-shell.

A repeated report of the same event type for the same installation, install_started included, returns the original result with "duplicate": true. A pre-install hook that runs several times counts one attempt.
Reusing an event_id with the same installation and type is idempotent. Reusing it for anything else is refused with event_id_conflict.
Destinations receive one conversion per installation and event type, identified by a stable event ID the platforms deduplicate on.

#Installation scopes

Use --installation-scope (or CLITRAIL_INSTALLATION_SCOPE) when one website ships several products, or one product can be installed several independent times on a machine. Each scope gets its own installation ID.

#Choosing the event

Use install_completed where your code runs at the end of a real install: a shell installer or an npm postinstall.
Use first_run where there is no install step you control: npx, Homebrew launchers, Python entry points and single binaries. It counts people who actually launch the CLI, not downloads.

Google Ads, Meta, TikTok and X Ads destinations send install_completed only until you tick first_run in their events; GA4 and webhooks send both by default. X Ads sends first runs to a second event of your pixel, so they never count as installs.

#Late receipts

An install is resolved when it is first reported. If it was unmatched, reporting it again does not attach a receipt that became readable later.