Analytics for builders
Read your site traffic from a terminal with no dashboard open
By Nora Blake · Nov 6, 2026 · 8 min read
Run the first command
The command line runs through npx, so there is nothing to install. The first time, store an API key. You create keys on your settings page, and the login prompt asks for one:
npx @usepeeko/cli login
npx @usepeeko/cli sites
npx @usepeeko/cli summary --site acme.com --range 7d
sites lists the sites your key can read, with their ids and domains. summary is the one most people want first. The range defaults to 7 days, so the --range 7d above is spelled out only for clarity.
The key is saved to ~/.config/peeko/config.json, or to $XDG_CONFIG_HOME/peeko/config.json if that variable is set, and the file is readable only by you. If you would rather write nothing to disk, set the key in the environment instead:
export PEEKO_API_KEY=your_key_here
export PEEKO_SITE=acme.com
npx @usepeeko/cli summary
With PEEKO_SITE set you can drop --site from every command. A key that reaches only one site also works without it. whoami shows which key is in use, how many sites it reaches and which site is the default.
If you have no account yet, npx @usepeeko/cli signup --email [email protected] emails a sign-in link. The trial is fourteen days with no card, it starts when you create your account, and it covers one site. init then creates a site and prints the install snippet plus a prompt you can hand to a coding agent. The one-session install guide walks through that path.
The crawler numbers a page script never sees
Most of what a terminal shows is the same as a dashboard: visitors, pages, sources. One command is worth running even if you never look at a dashboard, because the thing it reads cannot be seen from the browser at all.
AI crawlers do not run JavaScript. A script tag in the page never fires for them. Peeko counts them on a separate server side path, through the @usepeeko/bot-track middleware, which is ESM only, needs Node 20 or newer, has zero runtime dependencies and weighs under 3 KB gzipped. The bots command reads that path:
npx @usepeeko/cli bots --site acme.com --range 30d
npx @usepeeko/cli bots --site acme.com --range 30d --provider openai
Without --provider, bots shows which AI crawlers visited and what they read. With it, the output narrows to one AI company. Peeko matches the user agent against a curated list of 55 agents from 21 companies and files each recognized hit under AI answers, Search indexing, AI training or Other AI bots. The raw user agent is kept up to 512 characters, so old hits can be reclassified as the list grows. No address and no visitor hash exist on this path at all.
Why look at it? Because crawler reads and human visits are far apart, and the gap differs by company. Cloudflare published crawl to referral ratios measured on its own network for January and July 2025:
Source: Cloudflare, Crawlers, clicks and AI bots training, Aug 29, 2025. Retrieved Nov 3, 2026.
Read that chart with its limits in mind. It is one network's traffic, from July 2025, and each ratio is the number of crawler requests per human referral for a whole company, not for any one site. It tells you the shape of the gap, not what your own site will show. Your own bots output is the number that applies to you. For how to judge a count that looks too high, see the check for a scanner in a crawler costume.
Visits that arrive from ChatGPT, Claude, Perplexity, Copilot and Gemini are a different thing. Those are people, and Peeko counts them from ordinary page views by their referrer, with no middleware involved. They show up in sources. The referrer counting guide explains how that works and where it breaks.
Match the question to the command
Each question you would ask a dashboard has a command:
| Question | Command |
|---|---|
| How much traffic is the site getting? | summary |
| Which pages are read most? | pages |
| Where do visitors come from? | sources |
| Which pages keep people longest? | engagement |
| Who is on the site right now? | live |
| Which AI crawlers read the site? | bots |
| Are goals being hit? | goals |
| Where do people drop out of a funnel? | funnels |
| What did the site earn? | revenue |
| What do people search for before they arrive? | search, queries, search-pages |
| Which pages bring a goal its conversions? | goal-pages |
| What does a metric mean? | explain |
live --watch refreshes every 20 seconds until you press Ctrl+C, which is the closest a terminal gets to a dashboard left open on a second monitor. explain prints what each metric means in Peeko's own wording, which is useful when an agent or a teammate asks what "bounce after one page" counts.
Ranges, filters and limits
Every command takes the same few options:
--rangeacceptstoday,24h,7d,30d,90dorall. For a custom window, use--fromand--towith dates as YYYY-MM-DD.--filter key=valuenarrows every number to one dimension, and you can repeat it.--limit nreturns 1 to 100 rows onpages,sources,queries,search-pagesandgoal-pages.--providerpicksgoogleorbingonsearchandqueries.--viewonqueriespickstop,winners,losersoropportunities.
Run npx @usepeeko/cli help for the full reference. It works without a key.
Pipe the numbers somewhere
Two flags make the output usable by other programs. --json prints the raw payload with the original field names. --csv prints RFC 4180 CSV for pages, sources, engagement, goals, funnels, queries, search-pages and goal-pages. The two cannot be combined.
npx @usepeeko/cli pages --site acme.com --range 30d --limit 20 --csv > pages.csv
npx @usepeeko/cli goals --site acme.com --json
goal-pages needs a goal id, and goals --json is where you find it:
npx @usepeeko/cli goal-pages --site acme.com --goal GOAL_ID --range 90d --csv
A goal is a definition rather than a counter, so a goal written today counts over months before it was written. A goal-pages run over 90 days is therefore meaningful the day you create the goal. If you have only a handful of conversions, the first-goal guide covers how to read small numbers without fooling yourself.
Use it in a script
Exit codes make the command safe to schedule. 0 means success. 1 means the command ran and failed, and retrying unchanged will fail again. 2 means it could not run because the key was rejected, you were rate limited or there was no network, and retrying may help. A small daily report looks like this:
#!/usr/bin/env bash
set -euo pipefail
export PEEKO_SITE=acme.com
out="report-$(date -u +%Y-%m-%d)"
npx @usepeeko/cli summary --range 24h > "$out-summary.txt"
npx @usepeeko/cli sources --range 24h --csv > "$out-sources.csv"
npx @usepeeko/cli bots --range 24h > "$out-bots.txt"
Run it from cron or a CI schedule with PEEKO_API_KEY set in the job's environment. Because set -e stops on a nonzero exit, a rejected key fails the job loudly instead of writing empty files.
Let an agent run the same reads
The command line speaks the same MCP endpoint an agent does, so a command and a tool call return the same numbers. The server lives at usepeeko.com/api/mcp, takes a bearer API key and is read only, with one exception: the tool that creates a site. It is scoped by construction to the sites of the teams you belong to.
Connecting Claude Code takes one line:
claude mcp add --transport http peeko https://usepeeko.com/api/mcp --header "Authorization: Bearer your_key_here"
The tools mirror the commands: list_sites, get_summary, get_top_pages, get_sources, get_engagement, get_live_now, get_bot_summary, list_goals, get_goal, list_funnels, get_funnel, get_revenue, get_search_summary, get_search_queries, get_search_pages and get_goal_pages. Call list_sites first, since the others need a site id. The MCP setup guide covers Cursor and other clients.
Use the CLI when you want the answer yourself, and the MCP tools when you want an agent to fetch it mid task. Since both return the same numbers, you can check an agent's claim by running the command it should have run.
What a terminal read does not hide
A terminal removes the charts, not the limits of the data. Three are worth knowing before you trust a number.
Search data lags. Google publishes search data about three days late and revises its three most recent days, so search and queries figures for the last few days will change. Bing's query rows are weekly buckets dated to a Friday, which is why a Bing position is derived and can be null. Google Search Console and Bing Webmaster Tools both connect read only, and their rows are kept for sixteen months.
Your own visits count. If you open your site a lot while building it, summary includes you, so exclude your own visits before you read much into a small number.
People are hashed, not followed. The People number counts a one way keyed hash of the address and browser string, mixed with the date and re salted every day, so nobody can be followed from one day to the next. A second hash without the date tells a returning visitor from a new one and underlies goals, funnels and revenue. The address itself is never written to a database or a log.
A first-week routine
For the first week after launch, three commands cover most of what matters: summary --range 24h for volume, sources --range 7d for where people came from, and bots --range 7d to confirm that crawlers are reading the pages you want read.
After that, add what your site needs: goals once you have defined one, funnels when you have a multi step path, revenue when a sale is recorded either from a window.peeko.revenue call or a verified Stripe webhook. The two revenue totals are never added together, and amounts in different currencies are listed rather than converted, so read each line as its own number.
Nothing in this list needs a browser. If a number looks wrong, explain and --json are the two places to start.