@nuxtseo/cli 0.2.0 → 0.3.0

package/skills/nuxtseo-cli/references/commands.md

@@ -19,8 +19,13 @@ It is available on `actions list`, `page inspect`, `page issues`, `vitals
 findings`, `backlinks recoverable`, `search analytics` row views, `search
 indexing urls`, `sitemaps urls` and `content briefs list`.
 
+The `search analytics` row views are `pages`, `keywords`, `countries`,
+`devices`, and `analysis`. `--all` on any other view exits `2`.
+
 ## Contents
 
+- Which command answers which question
+- One invocation for the whole Site
 - Account and Site
 - Assessment and Actions
 - Pages, Scans, and lab performance
@@ -32,11 +37,72 @@ indexing urls`, `sitemaps urls` and `content briefs list`.
 - Content Briefs, Timeline, and annotations
 - Ask the CLI for its own help
 
+## Which command answers which question
+
+Ask one question, run one command. Stop when it is answered. Every command in
+this table reads stored evidence. None of them mutates, and none of them spends
+a research unit.
+
+| Question | Command |
+| --- | --- |
+| Is my token valid, and what may it do | `whoami` |
+| Which Site am I working on | `sites list` |
+| What is wrong with this Site | `status` |
+| What should I fix first | `actions list` |
+| Why does this action exist | `actions show <action-id>` |
+| Which exact URLs does it affect | `page issues`, with `--action-id` |
+| What does NuxtSEO know about one URL | `page inspect <url>` |
+| Did my last deploy break anything | `audit changes` |
+| How much of the Site is indexed | `search indexing summary` |
+| Which route family is Google declining | `search cohorts` |
+| Why is this one URL not indexed | `search inspect <url>` |
+| When did this URL change index state | `search index-history`, with `--url` |
+| Which pages earn the clicks | `search analytics pages` |
+| Which terms is the Site visible for | `search analytics keywords` |
+| Which pages are losing clicks | `audit content-decay` |
+| Where does internal link equity go | `audit link-structure` |
+| Is the Site slow for real users | `vitals summary`, then `vitals findings` |
+| Is the Site slow in the lab | `performance`, then `scans list` |
+| Which lab check failed | `scans show <scan-id>` |
+| Have I spent my limits | `usage` |
+
+Start at `status` for a Site you do not know. It carries the verdict and one
+ranked Next Action, so it replaces several of the rows below it.
+
+## One invocation for the whole Site
+
+| Command | What it returns, and its flags |
+| --- | --- |
+| `pull` | Every stored-evidence read for one Site, as NDJSON on stdout. One complete protocol envelope per line, with the `command` it came from beside `data` and `meta`. Requires `--json`. `--include` and `--exclude` take comma separated command names or a command prefix, for example `audit`. `--with-research` adds the reads that can start live research. `--period 7d\|28d\|3m\|6m\|12m` sets the Search Console window. `--concurrency 1..8` (default 4) |
+
+Read this first when you need the whole picture. It replaces about forty single
+reads with one invocation.
+
+`pull` excludes every mutation, and every read that needs an argument it cannot
+invent, such as `page inspect`, `page issues`, `search inspect`, `actions show`,
+`scans show` and `content briefs show`. Run those yourself with the IDs `pull`
+returned.
+
+`pull` makes one request per read. It never follows pages, so a run costs
+exactly as many requests as it names on stderr. When a line reports more pages,
+run that one command again with `--all`.
+
+One failing read does not stop the run. It writes its error envelope on its own
+line and the others continue. The exit code reports the worst outcome, and the
+last line is a `CliError` value with `command: "pull"` that repeats it. An
+authentication failure stops the run early, because every later read would fail
+the same way.
+
+Progress, warnings and the spend notice go to stderr. Line order follows
+completion, not the catalogue, so read the `command` field rather than counting
+lines.
+
 ## Account and Site
 
 | Command | What it returns, and its flags |
 | --- | --- |
 | `whoami` | Credential, Team, role, granted scopes, token expiry. The cheapest health check. Reads no Site |
+| `feedback submit` | Submit sanitized agent feedback. Requires `--command` (1..200 characters), `--comment` (1..2000), `--agent` (1..100), and `--yes`. Optional `--intent bug\|improvement` (default `bug`) and `--request-id` (1..128). Adds the CLI version. Needs no Site. Returns the feedback ID and status |
 | `login` | Pairs the CLI with a Team through the browser. A person must approve the pairing, so ask the user to run it. `--with-token` reads a token from a hidden prompt or stdin. `--no-browser` skips opening the browser |
 | `logout` | Discards the stored credential. Returns a `CliLogout` value |
 | `sites list` | Every accessible Site. The source of Site IDs |
@@ -83,7 +149,7 @@ indexing urls`, `sitemaps urls` and `content briefs list`.
 | Command | What it returns, and its flags |
 | --- | --- |
 | `search status` | Stored Search Console connection state. Provider free. Never waits for Google |
-| `search analytics <view>` | Search Console rows, trend, detail, or analysis. Views: `pages`, `keywords`, `countries`, `devices`, `timeseries`, `page-detail`, `keyword-detail`, `analysis`. `--period`, `--limit`, `--page`, `--search`, `--sort`, `--filter`, `--min-clicks`, `--max-clicks`, `--min-impressions`, `--max-impressions`, `--min-position`, `--max-position`, `--max-ctr`. The `analysis` view needs `--preset`, and the brand presets also need `--brand-terms` |
+| `search analytics <view>` | Search Console rows, trend, detail, or analysis. Views: `pages`, `keywords`, `countries`, `devices`, `timeseries`, `page-detail`, `keyword-detail`, `analysis`. `--period 7d\|28d\|3m\|6m\|12m` (default `28d`). No other period value is accepted; `90d` exits `2`, and `3m` is the three-month window. `--limit 1..100` (default 25), `--page` (default 1), `--search`, `--sort clicks\|impressions\|ctr\|position` (default `clicks`), `--sort-dir asc\|desc` (default `desc`), `--filter top-level\|new\|lost\|improving\|declining`, `--min-clicks`, `--max-clicks`, `--min-impressions`, `--max-impressions`, `--min-position 1..100`, `--max-position 1..100`, `--max-ctr 0..1`. The `page-detail` view needs `--page-url`, `keyword-detail` needs `--keyword`, and `analysis` needs `--preset`. The brand presets also need `--brand-terms` |
 | `search indexing <summary\|urls>` | Retained URL Inspection coverage. `summary` returns indexed counts. `urls` supports `--issue`, `--status`, `--limit 1..500` (default 50), `--offset` |
 | `search index-history` | Retained indexing changes and candidate causes. `--url`, `--field`, `--days 1..730`. Dates a regression against a release |
 | `search inspect <url>` | Google's own verdict for one URL. Takes an absolute URL or a site-relative path |
@@ -98,11 +164,37 @@ Analysis presets for `search analytics analysis` are `striking-distance`,
 `movers-rising`, and `movers-declining`. `brand-only` and `non-brand` also need
 `--brand-terms`. A missing argument exits `2` before any request.
 
+### Three totals on one `search analytics` response
+
+The `pages`, `keywords`, `countries`, and `devices` views return three
+different numbers. Read the one that answers your question.
+
+| Field | What it counts |
+| --- | --- |
+| `total` | The number of rows the query matched, not clicks or impressions |
+| `totals` | Clicks, impressions, CTR and position for the full upstream query population. `totalsScope` says so in words. It may include rows outside this page. `null` when the server has no total |
+| `representedTotals` | Clicks and impressions for the rows in this response only, after local filtering. `representedTotalsScope` says so in words |
+
+So `representedTotals` is at or below `totals`, and raising `--limit` moves
+`representedTotals` while leaving `totals` still. Never sum `rows` by hand when
+`totals` is present.
+
+### Never compare a keyword total with a page total
+
+Google suppresses query rows below a privacy threshold. So the `keywords` view
+sees a fraction of the traffic the `pages` view sees. On a typical property
+that is roughly half the impressions. Query-dimension totals are therefore
+always at or below page-dimension totals for the same Site and period. Never
+compare the two, and never report one as the Site total.
+
+Read the `pages` view for "how much traffic". Read the `keywords` view for
+"which terms are visible". A missing query row is never evidence of no demand.
+
 ## Web Analytics
 
 | Command | What it returns, and its flags |
 | --- | --- |
-| `analytics <view>` | Web Analytics from the connected provider. Views: `performance`, `top-pages`, `source-medium`, `key-events`, `countries`, `devices`, `dimension`. `--period`, `--compare`, `--dimension`, `--filters` |
+| `analytics <view>` | Web Analytics from the connected provider. Views: `performance`, `top-pages`, `source-medium`, `key-events`, `countries`, `devices`, `dimension`. `--period` is a free string, for example `28d` (default `28d`); an empty value exits `2`. `--compare previous\|year\|none` (default `previous`), `--dimension` (required for the `dimension` view; one of `date`, `page`, `hostname`, `source`, `medium`, `campaign`, `country`, `region`, `city`, `deviceCategory`, `browser`, `operatingSystem`), `--filters` as a JSON array, `--phase current\|prior\|full` (default `full`), `--no-stable-data` to include unstable recent days, `--no-host-scope` to include every host, `--no-compare-prior` to skip the prior window, `--fresh` to bypass the server cache |
 
 ## Research, backlinks, and mentions
 
@@ -112,28 +204,28 @@ research boundary in SKILL.md first.
 
 | Command | What it returns, and its flags |
 | --- | --- |
-| `research overview` | Stored Site and competitor research: metrics, history, gaps, quick wins |
-| `research keywords <topic>` | Live keyword ideas, with volume, difficulty, intent, and cost data |
-| `research serp <keyword>` | A live SERP snapshot: results, features, fetch time |
-| `research rankings <domain>` | Live domain rankings: current keywords and domain metrics |
+| `research overview` | Stored Site and competitor research: metrics, history, gaps, quick wins. Takes no flags. Returns `data.competitors` and `data.summary` |
+| `research keywords <topic>` | Live keyword ideas, with volume, difficulty, intent, and cost data. The seed must be 1 to 3 words. The server refuses a longer seed. The refusal arrives as exit `0` with an empty `data.keywords`, so read `data.message` first. Comma-separate several short seeds instead. Special characters are stripped before the lookup. If a seed is under 2 characters after stripping, the server refuses it the same way. The server applies default filters and echoes them in `data.filters`: `--min-volume` (default 10), `--max-volume` (default 10000), `--min-difficulty 0..100` (default 0), `--max-difficulty 0..100` (default 60). So a default run hides keywords over difficulty 60 or under 10 searches. Also `--limit 1..100` (default 20), `--intent`, `--location-code` (default 2840), `--no-related` to drop related keywords, and `--verbose` for full evidence. If `--max-volume` is under `--min-volume`, the run exits `2`. The same holds for `--max-difficulty` under `--min-difficulty` |
+| `research serp <keyword>` | A live SERP snapshot: results, features, fetch time. `--depth 1..20` (default 10) sets how many organic results return. `--location-code` (default 2840). The keyword must be 2 to 200 characters. `data.cached` reports cache use |
+| `research rankings <domain>` | Live domain rankings: current keywords and domain metrics. `--limit 1..100` (default 50), `--min-position 1..100` (default 1), `--max-position 1..100` (default 20), `--location-code` (default 2840), `--order position\|traffic` (default `position`). So a default run returns only the top 20 positions. If `--max-position` is under `--min-position`, the run exits `2`. An unusable domain also exits `2`, with `invalid_request`. An empty `data.keywords` with exit `0` carries the reason in `data.message`. `data.cached` reports cache use |
 | `research domain-traffic <domain>` | A live organic traffic estimate for any domain: trend, top pages, top countries. The domain does not have to be one of your Sites |
 | `research domain-availability <domains>` | Registration status. One comma-separated positional, up to 10 domains |
-| `backlinks summary` | Whole-domain inbound link totals. `evidence` reports cache use. Needs a Site URL |
+| `backlinks summary` | Whole-domain inbound link totals for the Site's own domain: `backlinks`, `referringDomains`, `referringPages`, `brokenBacklinks`, `brokenPages`, `crawledPages`, `spamScore`, `rank`. Takes no flags; it always reads the registered Site URL, so use `research domain-traffic` for any other domain. Every count is nullable. A `null` count means the provider returned no value. Never read it as zero. `evidence` reports cache use. Needs a Site URL |
 | `backlinks referring-domains` | Domains that link to the Site. `--limit 1..1000` (default 100). `sessions` is 90-day referral traffic, or null when no Web Analytics property is linked. Needs a Site URL |
 | `backlinks anchors` | Anchor text distribution of inbound links. `--limit 1..1000` (default 100). Needs a Site URL |
 | `backlinks history` | A monthly inbound link series. `--from YYYY-MM-DD`. Defaults to about twelve months. Needs a Site URL |
 | `backlinks recoverable` | Stored recoverable backlinks. `--limit 1..200`, `--offset`. Reads retained rows |
-| `mentions list` | Stored mentions. `--limit 1..200`. Reads retained rows |
+| `mentions list` | Stored mentions. `--limit 1..200` (default 100), `--include-filtered` to keep the Mentions AI triage marked a false positive. Reads retained rows |
 
 ## Crawl audit
 
 | Command | What it returns, and its flags |
 | --- | --- |
 | `audit changes` | The latest crawl compared with its baseline. `--from`, `--to`. The read for "did my deploy break anything" |
-| `audit link-opportunities` | Stored internal link opportunities, with crawl coverage |
-| `audit link-structure` | Template links, dead ends, and generic anchors. Shows where link equity goes |
-| `audit content-decay` | Stored decaying Pages, with Search Console loss evidence |
-| `audit duplicates` | Stored duplicate clusters, with members and keep candidate |
+| `audit link-opportunities` | Stored internal link opportunities, with crawl coverage. Takes no flags. Read `connected` and `pagesScanned` before quoting `total` |
+| `audit link-structure` | Template links, dead ends, and generic anchors. Shows where link equity goes. Takes no flags. It returns three separate lists: `templateSlots`, `deadEnds`, and `genericAnchors`. Each carries its own total. `deadEndScanTruncated: true` marks the dead-end list as a floor |
+| `audit content-decay` | Stored decaying Pages, with Search Console loss evidence. Takes no flags. If `connected` is `false`, the Site has no Search Console data. Never report that as clean. `truncated: true` marks the list as a floor |
+| `audit duplicates` | Stored duplicate clusters, with members and keep candidate. Takes no flags. `crawlSettingsId: null` means the Site never completed a crawl. Then `total: 0` proves nobody looked. Never report it as a clean Site |
 
 ## Content Briefs, Timeline, and annotations
 

package/skills/nuxtseo-cli/references/protocol.md

@@ -18,6 +18,29 @@ Protocol failure, still on stdout, with recovery details on stderr:
 
 Read `data`. The CLI does not unwrap, rename, rank, or enrich fields.
 
+## A soft failure looks like an empty result
+
+Some commands refuse the argument and still exit `0` with an empty list. The
+reason sits in `data.message`. A repair hint sits in `data.tip`. Read both
+before you read the list. Otherwise you report "nothing found" for a request
+the server never ran.
+
+These fields carry the reason:
+
+| Command | Fields |
+| --- | --- |
+| `research keywords` | `data.message`, `data.tip` |
+| `research rankings` | `data.message` |
+| `research domain-traffic` | `data.message` |
+| `research domain-availability` | `data.message` |
+| `page issues` | `data.message`, plus `availableKeys` |
+| `search cohorts` | `data.message`, plus `reason` |
+| `vitals findings` | `data.message`, plus `source` |
+
+`evidence._tag: "no-provider"` does not prove the data is absent. On `research
+keywords` it also marks a refused argument. The provider was never asked. Read
+`data.message` to tell the two cases apart.
+
 Local outcomes have no server body. They carry one tag and their own schema
 version. `CliHelp` uses version 2. The other values use version 1.
 
@@ -58,6 +81,10 @@ One invocation makes one request by default. The CLI never merges responses.
 writes one complete envelope per page, newline delimited, so parse the stream
 one JSON value per line. Nothing is merged, unwrapped, or re-ranked.
 
+`pull` writes the same stream for a whole Site. Each line is one operation's
+envelope with a `command` field beside `data` and `meta`. `pull` makes one
+request per operation and never follows pages, so it needs no cap of its own.
+
 The `--all` loop stops after 50 requests. If pages remain, the CLI exits `9`
 and stderr names the argument that resumes the read, for example `--offset 50`.
 Treat exit `9` as a stop, never as the end of the data.
@@ -65,6 +92,50 @@ Treat exit `9` as a stop, never as the end of the data.
 Pass the reported `offset` or opaque `cursor` for another page. Never edit or
 infer a cursor. Keep server order for actions. Never re-rank merged results.
 
+## List key and paging shape per command
+
+There is no single list key. Read the key this command returns; never guess a
+chain. Verified against the response schemas.
+
+| Command | List key | Paging fields |
+| --- | --- | --- |
+| `sites list` | `data.sites` | none; `meta.total` |
+| `usage` | `data.meters` | none |
+| `actions list` | `data.actions` | `data.page.total`, `.limit`, `.offset`, `.hasMore` |
+| `actions show` | `data.evidenceGroups[].items` | `data.evidenceGroups[].nextCursor` |
+| `page inspect` | `data.observations.rows` | `data.observations.total` and `data.observations.pagination.limit`, `.offset`, `.hasMore` |
+| `page issues` | `data.issues` | `data.total`, `data.limit`, `data.offset` |
+| `scans list` | `data.scans` | `data.total`, `data.limit` |
+| `scans pages` | `data.pages` | `data.total` |
+| `vitals findings` | `data.findings` | `data.total`, `data.limit`, `data.offset` |
+| `search analytics` row views | `data.rows` | `data.total`; page with `--page` |
+| `search analytics timeseries` | `data.daily` | none |
+| `search indexing urls` | `data.urls` | `data.total`, `data.limit`, `data.offset`, `data.hasMore` |
+| `search index-history` | `data.changes` | none |
+| `search cohorts` | `data.established` and `data.ranked` | `data.rankedTotal` |
+| `sitemaps list` | `data.sitemaps` | none |
+| `sitemaps urls` | `data.items` | `data.page.nextCursor`, `data.page.limit` |
+| `audit content-decay` | `data.rows` | `data.total`, `data.truncated` |
+| `audit link-opportunities` | `data.rows` | `data.total` |
+| `audit duplicates` | `data.clusters` | `data.total` |
+| `audit link-structure` | `data.templateSlots`, `data.deadEnds`, `data.genericAnchors` | one total per list |
+| `research keywords` | `data.keywords` | `data.totalFound` |
+| `research serp` | `data.results` | none; `data.depth` |
+| `research rankings` | `data.keywords` | `data.totalFound` |
+| `research domain-availability` | `data.results` | none |
+| `backlinks referring-domains` | `data.items` | `data.total`, `data.limit` |
+| `backlinks anchors` | `data.items` | `data.total`, `data.limit` |
+| `backlinks history` | `data.items` | `data.total` |
+| `backlinks recoverable` | `data.items` | `data.total`, `data.limit`, `data.offset` |
+| `mentions list` | `data.items` | `data.limit` |
+| `content briefs list` | `data.briefs` | `data.page.total`, `.limit`, `.offset`, `.hasMore` |
+| `timeline list` | `data.entries` | `data.nextCursor` |
+| `annotations list` | `data.annotations` | `data.total`, `data.limit` |
+
+Four paging shapes appear above: a nested `data.page` object, flat `total`,
+`limit` and `offset` fields, an opaque `nextCursor`, and no paging at all. The
+table is today's reality, so re-read it after a CLI update.
+
 ## Exit codes
 
 Branch on the exit code, not message text.
@@ -77,7 +148,7 @@ Branch on the exit code, not message text.
 | `4` | Forbidden, scope, or entitlement failure | Report the plan or token blocker |
 | `5` | Conflict, stale evidence, or ambiguous Site | Re-read. Pass `--site` if ambiguous |
 | `6` | Rate limit, `quota_exhausted`, provider outage, or timeout | Read retry metadata, then wait |
-| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID. If the message names `contract_violation`, update the CLI first |
+| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID. If the message names `contract_violation`, follow its contract version lines |
 | `8` | Resource or Site not found | Run `sites list` for a valid Site ID |
 | `9` | `--all` reached its request cap | Resume with the argument stderr names |
 | `127` | Shell cannot find `nuxtseo` | Install the CLI |