Docs

Quick start.

Nothing to install and no account. Point npx agenttraffic at the logs you already have and read the report.

Run it

npx agenttraffic ./logs --days 7

Sources are files, folders or wildcards, and gzipped files are read as they are. With no arguments it looks for logs in the current folder and tells you what to run.

Pick a date range

Flag	Meaning
--days N	the last N full days, ending two days ago (CloudFront delivers logs late)
--start D --end D	a date range, both dates included
--hours N	the last N hours, ending at the last full hour (UTC)
--since T --until T	exact timestamps, until not included
--tz ZONE	time zone for day-based ranges

Log formats

CloudFront standard logs, current and legacy (the column order is read from the header line, never assumed), and the common and combined formats written by nginx, Apache and most other servers. Force a format with --format. Current-format CloudFront logs saved without a header line need --fields a,b,c.

Real or fake

Every request that claims to be a known agent is checked against the IP addresses its operator publishes. The three results are kept apart in every count: verified (inside the published addresses), unverified (the operator publishes none, so there is nothing to check against), spoofed (outside the published addresses). Requests without a usable client IP are not checked, and the report says why. npx agenttraffic update downloads fresh address lists; nothing else touches the network.

Fetching CloudFront logs

npx agenttraffic fetch cloudfront s3://bucket/prefix/ --days 7

Downloads just the hourly files for that range into ~/.local/share/agenttraffic, using the AWS CLI.

JSON

--json (or --json=report.json) writes a JSON file instead of the terminal report. The format is versioned so you can build on it; the schema ships in @agenttraffic/core as schema/report-v1.json.

Privacy

IP addresses are used in memory to verify agents and estimate distinct visitors, and are never written to the output. No tracking.