Docs

Run it

npx agenttraffic ./logs --days 7

Sources are files, directories or globs; .gz is read transparently. With no arguments it looks for logs in the current directory and says what to run.

Windows

| Flag | Meaning | | --- | --- | | --days N | N whole days ending two days ago (CloudFront delivery lag) | | --start D --end D | inclusive local dates | | --hours N | rolling N hours ending at the last complete UTC hour | | --since T --until T | ISO instants, until exclusive | | --tz ZONE | zone for day windows |

Formats

CloudFront standard logging v2 (header line parsed, columns never assumed), legacy CloudFront, and CLF / combined (nginx, Apache). Force one with --format. Headerless v2 plain logs need --fields a,b,c.

Verification

Every bot UA is checked against the IP ranges its operator publishes. The three states are kept separate in every count: verified (inside the range), unverified (operator publishes no range), spoofed (range published, IP outside it). Requests without a usable client IP are not checked and say why. npx agenttraffic update fetches fresh ranges; nothing else touches the network.

Fetching CloudFront logs

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

Syncs only the hourly files for the window into ~/.local/share/agenttraffic using the aws CLI.

JSON

--json (or --json=report.json) writes the versioned schema v1 report instead of the terminal view. The schema ships in @agenttraffic/core as schema/report-v1.json.

Privacy

Client IPs are used in memory for verification and distinct estimates and never written to output. No telemetry.