Docs Guides How it works How it works What happens during a login and a report run, what runs on your machine and what Google sees.
auditmyvisitors is one binary on your machine. It has no server of its own: everything it
knows comes from the Google APIs, read with your own login, and everything it keeps stays in
your config directory (see Data and privacy ).
Login
auditmyvisitors auth login uses the OAuth authorization code flow with PKCE, the flow Google
recommends for installed apps. The CLI opens Google’s consent page in your browser and waits
for the answer on a local listener at 127.0.0.1:9004. A random state value guards the
redirect; if it does not match, the login is aborted.
Focus auditmyvisitors auth login auditmyvisitors auth login The CLI creates a PKCE verifier and a random state, opens Google's consent page in the browser and waits on 127.0.0.1:9004. Google redirects back with a code; the CLI checks the state, exchanges code and verifier for tokens and stores them in tokens.json, readable by the owner only. 1. auditmyvisitors → Browser: open consent URL with challenge and state open consent URL with challenge and state 2. Browser → Google sign-in: you allow two read-only scopes you allow two read-only scopes 3. Google sign-in → Listener: redirect with code and state redirect with code and state 4. Listener → auditmyvisitors: query string query string 5. auditmyvisitors → Google sign-in: code and verifier for tokens code and verifier for tokens 6. Google sign-in → auditmyvisitors: access and refresh token access and refresh token 7. auditmyvisitors → tokens.json: save, mode 0600 save, mode 0600 auditmyvisitors – PKCE verifier, state auditmyvisitors PKCE verifier, state Browser Browser Google sign-in Google sign-in Listener – 127.0.0.1:9004 Listener 127.0.0.1:9004 tokens.json tokens.json Source: src/auth/pkce.rs, src/auth/server.rs, src/storage/mod.rs
Show chart data Data for auditmyvisitors auth login No. From To Message Kind 1 auditmyvisitors Browser open consent URL with challenge and state call 2 Browser Google sign-in you allow two read-only scopes call 3 Google sign-in Listener redirect with code and state call 4 Listener auditmyvisitors query string reply 5 auditmyvisitors Google sign-in code and verifier for tokens call 6 Google sign-in auditmyvisitors access and refresh token reply 7 auditmyvisitors tokens.json save, mode 0600 call
Focus auditmyvisitors auth login auditmyvisitors auth login The CLI creates a PKCE verifier and a random state, opens Google's consent page in the browser and waits on 127.0.0.1:9004. Google redirects back with a code; the CLI checks the state, exchanges code and verifier for tokens and stores them in tokens.json, readable by the owner only. 1. auditmyvisitors → Browser: open consent URL with challenge and state open consent URL with challenge and state 2. Browser → Google sign-in: you allow two read-only scopes you allow two read-only scopes 3. Google sign-in → Listener: redirect with code and state redirect with code and state 4. Listener → auditmyvisitors: query string query string 5. auditmyvisitors → Google sign-in: code and verifier for tokens code and verifier for tokens 6. Google sign-in → auditmyvisitors: access and refresh token access and refresh token 7. auditmyvisitors → tokens.json: save, mode 0600 save, mode 0600 auditmyvisitors – PKCE verifier, state auditmyvisitors PKCE verifier, state Browser Browser Google sign-in Google sign-in Listener – 127.0.0.1:9004 Listener 127.0.0.1:9004 tokens.json tokens.json Source: src/auth/pkce.rs, src/auth/server.rs, src/storage/mod.rs
Show chart data Data for auditmyvisitors auth login No. From To Message Kind 1 auditmyvisitors Browser open consent URL with challenge and state call 2 Browser Google sign-in you allow two read-only scopes call 3 Google sign-in Listener redirect with code and state call 4 Listener auditmyvisitors query string reply 5 auditmyvisitors Google sign-in code and verifier for tokens call 6 Google sign-in auditmyvisitors access and refresh token reply 7 auditmyvisitors tokens.json save, mode 0600 call
The access token is refreshed automatically with the stored refresh token when it has expired.
auditmyvisitors auth logout deletes tokens.json.
A report run
Every report and every export goes through the same steps. Nothing is cached between runs: each
run fetches live data, so the numbers match what GA4 and Search Console show at that moment.
Focus One report run One report run A report reads the selected property from config.toml and an access token from tokens.json, refreshing it at Google sign-in when it has expired. It then asks the GA4 Data API and, if a Search Console property is selected, the Search Console API, matches both per page, applies the insight rules and prints the result or writes an export. report overview also stores a snapshot of the day's key metrics. Your machine Google, read-only report or export → config.toml config.toml → Token expired? Token expired? → Google sign-in: yes Token expired? → GA4 Data API: no Google sign-in → GA4 Data API GA4 Data API → Search Console API: if selected GA4 Data API → Match per page: GA4 only Search Console API → Match per page Match per page → Insights, scores Insights, scores → Terminal Insights, scores → PDF, CSV, JSON: export Insights, scores → Snapshot: overview yes no if selected GA4 only export overview report or export – subcommand or menu report or export subcommand or menu config.toml – property, defaults config.toml property, defaults Token expired? – tokens.json Token expired? tokens.json Google sign-in – token refresh Google sign-in token refresh GA4 Data API – runReport GA4 Data API runReport Search Console API – search analytics Search Console API search analytics Match per page – GA4 path, Search Console URL Match per page GA4 path, Search Console URL Insights, scores – explicit rules Insights, scores explicit rules Terminal Terminal PDF, CSV, JSON PDF, CSV, JSON Snapshot – report overview Snapshot report overview Source: src/main.rs, src/auth/refresh.rs, src/google/, src/helpers/mod.rs, src/insights/, src/snapshots/, src/export/
Show chart data Data for One report run Step Kind Lane Leads to report or export start Your machine config.toml config.toml data store Your machine Token expired? Token expired? decision Your machine Google sign-in (yes), GA4 Data API (no) Google sign-in external Google, read-only GA4 Data API GA4 Data API external Google, read-only Search Console API (if selected), Match per page (GA4 only) Search Console API external Google, read-only Match per page Match per page step Your machine Insights, scores Insights, scores step Your machine Terminal, PDF, CSV, JSON (export), Snapshot (overview) Terminal end Your machine PDF, CSV, JSON end Your machine Snapshot data store Your machine
Focus One report run One report run A report reads the selected property from config.toml and an access token from tokens.json, refreshing it at Google sign-in when it has expired. It then asks the GA4 Data API and, if a Search Console property is selected, the Search Console API, matches both per page, applies the insight rules and prints the result or writes an export. report overview also stores a snapshot of the day's key metrics. Your machine Google, read-only report or export → config.toml config.toml → Token expired? Token expired? → Google sign-in: yes Token expired? → GA4 Data API: no Google sign-in → GA4 Data API GA4 Data API → Search Console API: if selected GA4 Data API → Match per page: GA4 only Search Console API → Match per page Match per page → Insights, scores Insights, scores → Terminal Insights, scores → PDF, CSV, JSON: export Insights, scores → Snapshot: overview yes no if selected GA4 only export overview report or export – subcommand or menu report or export subcommand or menu config.toml – property, defaults config.toml property, defaults Token expired? – tokens.json Token expired? tokens.json Google sign-in – token refresh Google sign-in token refresh GA4 Data API – runReport GA4 Data API runReport Search Console API – search analytics Search Console API search analytics Match per page – GA4 path, Search Console URL Match per page GA4 path, Search Console URL Insights, scores – explicit rules Insights, scores explicit rules Terminal Terminal PDF, CSV, JSON PDF, CSV, JSON Snapshot – report overview Snapshot report overview Source: src/main.rs, src/auth/refresh.rs, src/google/, src/helpers/mod.rs, src/insights/, src/snapshots/, src/export/
Show chart data Data for One report run Step Kind Lane Leads to report or export start Your machine config.toml config.toml data store Your machine Token expired? Token expired? decision Your machine Google sign-in (yes), GA4 Data API (no) Google sign-in external Google, read-only GA4 Data API GA4 Data API external Google, read-only Search Console API (if selected), Match per page (GA4 only) Search Console API external Google, read-only Match per page Match per page step Your machine Insights, scores Insights, scores step Your machine Terminal, PDF, CSV, JSON (export), Snapshot (overview) Terminal end Your machine PDF, CSV, JSON end Your machine Snapshot data store Your machine
Two sources, one view. GA4 reports page paths, Search Console full URLs. Where a report
uses both, they are matched per page path, so sessions and engagement sit next to clicks,
impressions, CTR and position. Which reports need Search Console is listed under
Reports .Rules, not a language model. Insights, the management summary and the opportunity score
come from explicit rules in the code. The limits the insight rules use are settings in
config.toml , not constants.Snapshots. report overview stores the day’s key metrics, so a run on a later day can
show the change since then.Retries. Each Google request is tried up to three times on rate limits and server errors
and times out after 30 seconds.
The Google APIs it reads
API
Used for
Scope
Google Analytics Admin API
listing the GA4 properties you can read
analytics.readonly
Google Analytics Data API
traffic, engagement, channels, devices, countries
analytics.readonly
Search Console API
clicks, impressions, CTR, position; sitemaps and URL inspection for the PDF
webmasters.readonly
Both scopes are read-only: auditmyvisitors cannot change anything in GA4 or Search Console.
Edit this page on GitHub · Docs for v0.3.1