# The command line (/cli) The Peeko command line does what the dashboard does, with no browser. It needs no install: `npx` fetches it, runs it and forgets it. ```bash npx @usepeeko/cli summary --site acme.com --range 7d ``` It speaks the same MCP endpoint your agent does, so a command and a tool call return the same numbers from the same data. ## Sign in once [#sign-in-once] `login` prompts for an API key and stores it. Keys are made on your settings page, and a key reaches the sites of the organizations it belongs to. ```bash npx @usepeeko/cli login ``` The key is written to `$XDG_CONFIG_HOME/peeko/config.json`, or `~/.config/peeko/config.json`, readable only by you. `logout` forgets it, and `whoami` says which key is in use, how many sites it reaches and which one is the default. A key belongs to you, not to an organization, and it reaches the sites of every team you are in while that team's plan is active. If you would rather not store a key at all, set `PEEKO_API_KEY` in the environment instead. Every command reads it and no key is written to disk, though `peeko use` still records a default site there. ## Six commands worth knowing first [#six-commands-worth-knowing-first] ```bash npx @usepeeko/cli init ``` Creates a site and prints its snippet and the prompt to hand your agent. ```bash npx @usepeeko/cli sites ``` Every site the key can read. ```bash npx @usepeeko/cli summary --range 30d ``` People, visits, page views, time on site, left after one page and pages per visit, each against the previous window. ```bash npx @usepeeko/cli pages ``` The pages people actually read. ```bash npx @usepeeko/cli live ``` Who is on the site right now. ```bash npx @usepeeko/cli explain ``` What each metric means, in the product's own words. ## Which site, and which window [#which-site-and-which-window] Most commands read one site. Pass `--site` with an id, a domain, or a site name only one site has. You can leave it out when `PEEKO_SITE` is set, when `peeko use` has stored a default, or when the key reaches exactly one site. Ranges are `today`, `24h`, `7d`, `30d`, `90d` and `all`, or a custom window with `--from` and `--to`. Days are calendar days in the site's own time zone, so a range means the same thing here as it does on the dashboard. ```bash npx @usepeeko/cli summary --site acme.com --from 2026-08-01 --to 2026-08-31 --filter country=US --filter device=mobile ``` `--filter` narrows every number in the output, and repeats. `--json` prints the payload instead of the table, keeping the original field names, which is what to reach for when a script is reading. ## Which search engine [#which-search-engine] `search` and `queries` read Google Search Console or Bing Webmaster Tools, chosen with `--provider`. ```bash npx @usepeeko/cli search --site acme.com --range 30d --provider bing ``` Leave it out and Google answers when the site is linked to a Search Console property, Bing when it is linked only to a Bing site. The provider that answered is named in the output either way. Bing's query rows are weekly buckets, so a short range returns few of them; [Search Console and Bing](/search-console) explains why. `--provider` means something else on `bots`, where it narrows crawler numbers to one AI company. The flag is keyed by command, and `--help` on either says which meaning applies. ## Exit codes [#exit-codes] The split is by what you have to do about it, so a wrapper can retry on `2` and must not retry on `1`. | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------- | | `0` | The command succeeded. | | `1` | The command ran and failed. Running it again unchanged will fail again. | | `2` | The command could not be attempted: the key was rejected, you were rate limited, or there was no network. | A missing key and a rejected key both exit `2` and say different things, because they are different problems. ## Command reference [#command-reference] Every command, with the options it accepts. The two universal ones, `--help` and `--version`, work everywhere and are listed with each command rather than assumed. ### peeko login [#peeko-login] Store an API key for later commands. Prompts for the key. Runs without a key. | Option | What it does | | ----------- | ----------------------------------- | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko logout [#peeko-logout] Forget the stored API key. Runs without a key. | Option | What it does | | ----------- | ----------------------------------- | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko whoami [#peeko-whoami] Which key is in use, how many sites it reaches, and the default site. Needs a stored key. | Option | What it does | | ----------- | ----------------------------------- | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko init [#peeko-init] Create a new site and print everything needed to install it. Needs a stored key. | Option | What it does | | ------------------- | ----------------------------------------------------------------------------------------------------------- | | `--org ` | Which organization to create the site in. Only "init" uses it, and only when the key reaches more than one. | | `--name ` | Site name for "init". | | `--domain ` | Site domain for "init", without a scheme, for example acme.com. | | `--json` | Print the raw payload as JSON instead of a table. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko sites [#peeko-sites] List the sites this key can read, with their ids and domains. Needs a stored key. | Option | What it does | | ----------- | ------------------------------------------------- | | `--json` | Print the raw payload as JSON instead of a table. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko use [#peeko-use] Choose the default site, or print it. --none clears it. Runs without a key. | Option | What it does | | ----------- | --------------------------------------------------- | | `--none` | Clear the stored default site. Only "use" takes it. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko summary [#peeko-summary] Headline numbers for one site: people, visits, page views, time on site. Needs a stored key. | Option | What it does | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--filter =` | Narrow every number to one dimension. Repeatable, and the last value of a repeated key wins. Taken by summary, pages, sources and engagement. The keys: page, source, country, device, browser, browser\_version, os, os\_version, screen, viewport, utm\_source, utm\_medium, utm\_campaign. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko pages [#peeko-pages] Most viewed pages. Needs a stored key. | Option | What it does | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--filter =` | Narrow every number to one dimension. Repeatable, and the last value of a repeated key wins. Taken by summary, pages, sources and engagement. The keys: page, source, country, device, browser, browser\_version, os, os\_version, screen, viewport, utm\_source, utm\_medium, utm\_campaign. | | `--limit ` | How many rows to return, from 1 to 100. Without it each command keeps its own default. "pages", "sources" and "queries" only. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko sources [#peeko-sources] Where visitors came from. "Direct" means no referrer. Needs a stored key. | Option | What it does | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--filter =` | Narrow every number to one dimension. Repeatable, and the last value of a repeated key wins. Taken by summary, pages, sources and engagement. The keys: page, source, country, device, browser, browser\_version, os, os\_version, screen, viewport, utm\_source, utm\_medium, utm\_campaign. | | `--limit ` | How many rows to return, from 1 to 100. Without it each command keeps its own default. "pages", "sources" and "queries" only. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko engagement [#peeko-engagement] Pages ranked by how long people stay. Needs a stored key. | Option | What it does | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--filter =` | Narrow every number to one dimension. Repeatable, and the last value of a repeated key wins. Taken by summary, pages, sources and engagement. The keys: page, source, country, device, browser, browser\_version, os, os\_version, screen, viewport, utm\_source, utm\_medium, utm\_campaign. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko live [#peeko-live] Who is on the site right now. Needs a stored key. | Option | What it does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--json` | Print the raw payload as JSON instead of a table. | | `--watch` | Re-read "live" every 20 seconds, clearing the screen between renders, until Ctrl+C. Needs a terminal. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko bots [#peeko-bots] AI crawler traffic: which bots read the site, and what they read. Needs a stored key. | Option | What it does | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--provider ` | Which provider, and it means two different things. On "bots" it narrows to one AI company, for example OpenAI or Anthropic, and every number and list is then that company's alone. On "search" and "queries" it picks a search engine, google or bing; without it Google answers when the site is linked to a Search Console property and Bing when it is linked only to a Bing site. Case does not matter; a value Peeko does not know is refused. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko goals [#peeko-goals] Goals with their counts and conversion. Needs a stored key. | Option | What it does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko funnels [#peeko-funnels] Funnels step by step, with where people drop out. Needs a stored key. | Option | What it does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko revenue [#peeko-revenue] Money for a range, by source and by page. Needs a stored key. | Option | What it does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--json` | Print the raw payload as JSON instead of a table. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko search [#peeko-search] Google or Bing clicks, impressions, CTR and average position. Needs a stored key. | Option | What it does | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--provider ` | Which provider, and it means two different things. On "bots" it narrows to one AI company, for example OpenAI or Anthropic, and every number and list is then that company's alone. On "search" and "queries" it picks a search engine, google or bing; without it Google answers when the site is linked to a Search Console property and Bing when it is linked only to a Bing site. Case does not matter; a value Peeko does not know is refused. | | `--json` | Print the raw payload as JSON instead of a table. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko queries [#peeko-queries] Search queries by clicks, or the ones that gained, lost or nearly rank. Needs a stored key. | Option | What it does | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | Which site to read: an id, a domain, or a site name that only one site has. Optional when PEEKO\_SITE is set, when "peeko use" has stored a default, or when the key reaches exactly one site. Every value is resolved against your site list, which is one extra call. | | `--range ` | Time window. Ranges: today, 24h, 7d, 30d, 90d, all, or --from and --to (YYYY-MM-DD). Default 7d. Day ranges and Today follow the site's time zone, which is UTC until the owner sets one in the site's settings. 24h is the last 24 hours in any zone. | | `--provider ` | Which provider, and it means two different things. On "bots" it narrows to one AI company, for example OpenAI or Anthropic, and every number and list is then that company's alone. On "search" and "queries" it picks a search engine, google or bing; without it Google answers when the site is linked to a Search Console property and Bing when it is linked only to a Bing site. Case does not matter; a value Peeko does not know is refused. | | `--json` | Print the raw payload as JSON instead of a table. | | `--csv` | RFC 4180 CSV instead of a table, on pages, sources, engagement, goals, funnels and queries. The table's own columns, in the table's order, and no prose. Refused with --json. | | `--view ` | Which view of the search queries: top, winners, losers or opportunities. Default top. "queries" only. | | `--limit ` | How many rows to return, from 1 to 100. Without it each command keeps its own default. "pages", "sources" and "queries" only. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko explain [#peeko-explain] What Peeko's metrics mean, in Peeko's own words. Needs a stored key. | Option | What it does | | ----------- | ----------------------------------- | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko signup [#peeko-signup] Send yourself a sign-in link and start an account. Needs no key. Runs without a key. | Option | What it does | | ------------------- | ----------------------------------------------------------------------------------------- | | `--email
` | Where to send the sign-in link. "signup" only, and the one option that works with no key. | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ### peeko help [#peeko-help] This page. Runs without a key. | Option | What it does | | ----------- | ----------------------------------- | | `--help` | Help for the command, or this page. | | `--version` | Print the CLI version. | ## Next [#next] * [Install Peeko](/install) if the tracker is not on the site yet. * [MCP](/mcp) for the same reads as agent tools.