@nuxtseo/cli 0.1.3 → 0.2.0

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

@@ -0,0 +1,162 @@
+# CLI command reference
+
+Every command, with the flags you need most, their ranges, and their defaults.
+Some commands take more flags than a row lists. Ask the command itself for the
+full set: `nuxtseo <command> --help --json`.
+
+Pass `--json` and `--site <site-id>` on every command below, except `whoami`,
+`sites list`, `config`, and `skill install`.
+
+`Mutation` marks a command that changes server state. A mutation needs `--yes`
+in a non-interactive shell.
+
+`Needs a Site URL` marks a command that reads the Site's own domain. If the Site
+has no URL, the command exits `2`. Set the Site URL first; retrying will not
+help.
+
+`--all` repeats a paged read until every page is written, one envelope per line.
+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`.
+
+## Contents
+
+- Account and Site
+- Assessment and Actions
+- Pages, Scans, and lab performance
+- Field Core Web Vitals
+- Search Console and sitemaps
+- Web Analytics
+- Research, backlinks, and mentions
+- Crawl audit
+- Content Briefs, Timeline, and annotations
+- Ask the CLI for its own help
+
+## 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 |
+| `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 |
+| `sites use <site-id>` | Persists a default Site in local config, for the human, not for you |
+| `usage` | `data.plan`, and `data.meters[]` carrying `used`, `limit` and `blocked` per limit. `--group integrations\|compute\|capacity` |
+| `config` | Local config path, API host, selected Site. Local only |
+| `skill install` | Copies this skill into an agent skill directory. `--agent claude\|codex`, `--target <dir>` |
+
+## Assessment and Actions
+
+| Command | What it returns, and its flags |
+| --- | --- |
+| `status` | The Site assessment in one read: verdict, the single ranked Next Action, open and verified counts, degraded pipeline steps, recent changes, Receipts. `available: false` means the first assessment has not run. If the Site is archived or paused, this exits `4` or `5` rather than answering |
+| `actions list` | Server-ranked issues and opportunities. `--limit 1..25` (default 10), `--offset`. Each row carries `evidence.freshness`; `verdict: "aged"` means the observation is over a day old, so live-check before fixing |
+| `actions show <action-id>` | One issue or opportunity, plus its evidence. `--limit 1..100` (default 50), `--group-id`, `--cursor` |
+| `actions resolve <action-id>` | Mutation. Claims the issue or opportunity and starts server verification. Reads the action first and sends `artifactVersion` for you |
+| `actions dismiss <action-id>` | Mutation. Says the page stays removed. Needs `--artifact-version`, read from `actions show`. Admitted only for a broken-page action with complete 404 or 410 evidence and no internal referrers |
+
+## Pages, Scans, and lab performance
+
+| Command | What it returns, and its flags |
+| --- | --- |
+| `page inspect <url>` | Stored observations, Lighthouse rows and keywords for one Page. `--limit 1..200`, `--offset`, `--include-resolved`. Carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
+| `page issues` | Raw Page Issue rows. Pass `--action-id`, or pass both `--source` and `--issue`. Passing both selectors exits `2`. `--url`, `--path-prefix`, `--include-resolved`, `--limit 1..200`, `--offset`. When the selector matches nothing, `availableKeys` lists the pairs this Site does have. If the Site is archived or paused, this exits `4` or `5` rather than answering |
+| `page scan <url>` | Mutation. Starts a mobile Scan and a desktop Scan |
+| `performance` | Stored Lighthouse lab overview for the Site: medians for perf, a11y, SEO, LCP, TBT, CLS. Lab Scans, never real-user field data |
+| `scans list` | Retained Lighthouse Scans, newest first, with scores, lab vitals, and the error on a failed Scan. `--limit 1..100` (default 25) |
+| `scans show <scan-id>` | One Scan, and the evidence behind its scores: wasteful assets, repeat-visit cache policy, third-party scripts, the LCP element, and every failing accessibility and best-practices check with its CSS selectors and DOM snippets. Read `coverage` before quoting a total |
+| `scans pages` | The Pages this Site scans on a schedule. Add one with `page scan <url>` |
+
+`page inspect` and `page scan` take an absolute URL, for example
+`https://example.com/about`.
+
+## Field Core Web Vitals
+
+| Command | What it returns, and its flags |
+| --- | --- |
+| `vitals summary` | Field Core Web Vitals from CrUX: the latest p75, plus its change over the window. `--url` for one Page, `--form-factor phone\|desktop\|all`. `available: false` means the target is under the CrUX traffic floor |
+| `vitals trend` | A 25-week field p75 series. Same inputs as `vitals summary` |
+| `vitals findings` | Failing field vitals attributed to a DOM element. `--metric lcp\|inp\|cls`, `--limit 1..50` (default 20), `--offset`, `--no-only-failing`. Each finding carries the CSS selector and a ready-to-apply `fixPrompt`. Needs a connected Web Analytics provider |
+
+## Search Console and sitemaps
+
+| 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 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 |
+| `search cohorts` | Not-indexed rate per route family. `--limit 1..50` (default 12), `--min-pages 1..500` (default 5). If the Site is archived or paused, this exits `4` or `5` rather than answering |
+| `sitemaps list` | Search Console sitemap snapshot: errors, warnings, URL counts, sync status |
+| `sitemaps urls` | Sitemap URL membership. `--generation-id`, `--feedpath`, `--cursor`, `--limit 1..1000` |
+| `sitemaps submit <sitemap-url>` | Mutation. Submits one sitemap through the Site's stored Search Console credential |
+| `sitemaps delete <sitemap-url>` | Mutation. Removes one sitemap through the Site's stored Search Console credential |
+
+Analysis presets for `search analytics analysis` are `striking-distance`,
+`opportunity`, `decay`, `zero-click`, `non-brand`, `brand-only`,
+`movers-rising`, and `movers-declining`. `brand-only` and `non-brand` also need
+`--brand-terms`. A missing argument exits `2` before any request.
+
+## 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` |
+
+## Research, backlinks, and mentions
+
+Every command here can start live research, except `research overview`,
+`backlinks recoverable` and `mentions list`, which read retained rows. Read the
+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 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 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 |
+
+## 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 |
+
+## Content Briefs, Timeline, and annotations
+
+| Command | What it returns, and its flags |
+| --- | --- |
+| `content briefs list` | Content Brief summaries. `--status`, `--limit`, `--offset` |
+| `content briefs show <brief-id>` | One Content Brief, including its grounded payload |
+| `content briefs create <keyword>` | Mutation. Creates one Content Brief. `--target-page` is optional |
+| `timeline list` | Stored Timeline Entries. `--kind`, `--feature`, `--severity`, `--since`, `--limit`, `--cursor`, `--include-closed` |
+| `annotations list` | This Site's own chart annotations: date-anchored markers on traffic and ranking charts |
+| `annotations create` | Mutation, so it needs `--yes`. Marks the day you shipped a fix. `--date YYYY-MM-DD` and `--title` are required. `--note` and `--url` are optional |
+| `annotations update <annotation-id>` | Mutation, so it needs `--yes`. Send only what changes. Pass `--note ""` or `--url ""` to clear that field |
+| `annotations delete <annotation-id>` | Mutation. Permanent |
+
+## Ask the CLI for its own help
+
+`--help --json` returns a `CliHelp` value for one command level. It separates
+positional `arguments`, command-specific `localOptions`, inherited
+`globalOptions`, and `subcommands`.
+
+```sh
+nuxtseo actions list --help --json
+```
+
+Use it instead of guessing a flag. Prefer the tables above for anything they
+already answer.

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

@@ -0,0 +1,60 @@
+# Indexing questions
+
+Read this before you report an indexed count, or name the URLs Google indexed.
+Two datasets answer indexing questions, and they are not interchangeable.
+Retained URL Inspection evidence says what Google decided. Search Console
+performance rows say which URLs appeared in search results.
+
+Start with the retained URL Inspection summary:
+
+```sh
+nuxtseo search indexing summary --site <site-id> --json
+```
+
+Report `data.totalUrls`, `data.indexed`, and `data.asOf`. These are exact for
+the retained URL Inspection evidence at that timestamp. They are not a live
+count of Google's whole index. State that boundary with the result. If
+`data.asOf` is null, say the retained snapshot time is unavailable. Never call
+that result current or live.
+
+Use the URL view when the user asks which URLs hold a verdict:
+
+```sh
+nuxtseo search indexing urls --site <site-id> --status indexed --all --json
+nuxtseo search indexing urls --site <site-id> --status not_indexed --all --json
+```
+
+Each output line is one protocol envelope. Use `data.total` for the exact
+filtered count. Read `data.urls` across every returned envelope for the URL
+list. If exit `9` stops the read, the list is Provisional. Resume from the
+offset on stderr when the full list matters.
+
+Before using `--all`, check that `--help --json` lists `all` in `localOptions`
+for that command. If it is absent, the installed CLI cannot page that command.
+Update the CLI.
+
+Never derive indexed URL counts from `search analytics`. Its Page rows show
+URLs with Search Console performance in the selected period. Impressions count
+search result appearances. A URL can be indexed with no impressions. A missing
+Page row does not prove that Google has not indexed it.
+
+For URLs that appeared in search results during the current period, read every
+Page row:
+
+```sh
+nuxtseo search analytics pages --site <site-id> --period 7d --all --json
+```
+
+Keep rows where `row.impressions > 0`. Count those rows, and report `row.url`
+when the user asks which URLs appeared. Do not use `data.total` for this count.
+It also includes comparison-period rows with zero current impressions.
+
+Keep these reads separate:
+
+| Question | Command | Report |
+| --- | --- | --- |
+| What is the indexed count for retained URLs? | `search indexing summary` | `totalUrls`, `indexed`, `asOf` |
+| Which retained URLs are indexed or not indexed? | `search indexing urls` | `total`, then the complete `urls` stream |
+| Which URLs appeared in the current period? | `search analytics pages` | Rows with `impressions > 0`, then each `url` |
+| What does Google say about one URL now? | `search inspect <url>` | The returned URL Inspection verdict |
+| Which URLs did the Site submit? | `sitemaps list`, then `sitemaps urls` | Sitemap totals and membership |

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

@@ -18,7 +18,8 @@ Protocol failure, still on stdout, with recovery details on stderr:
 
 Read `data`. The CLI does not unwrap, rename, rank, or enrich fields.
 
-Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
+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.
 
 | `_tag` | Written by |
 | --- | --- |
@@ -28,6 +29,7 @@ Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
 | `CliConfig` | `config --json` |
 | `CliLogout` | `logout --json` |
 | `CliSiteSelection` | `sites use <site-id> --json` |
+| `CliSkillInstall` | `skill install --json` |
 | `CliError` | Any failure with no server body |
 
 Discriminate on `_tag`. Protocol envelopes never carry one.
@@ -50,7 +52,15 @@ Set `NUXTSEO_NO_UPDATE_CHECK=1` to disable the check, for example in CI.
 
 ## Paging
 
-One invocation makes one request. The CLI never auto-pages or merges responses.
+One invocation makes one request by default. The CLI never merges responses.
+
+`--all` repeats the same operation until the server reports no more pages. It
+writes one complete envelope per page, newline delimited, so parse the stream
+one JSON value per line. Nothing is merged, unwrapped, or re-ranked.
+
+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.
 
 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.
@@ -66,14 +76,16 @@ Branch on the exit code, not message text.
 | `3` | Missing, invalid, or expired authentication | Ask the user for a token |
 | `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, provider outage, or timeout | Read retry metadata, then wait |
+| `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 |
 | `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 |
 | `130` | Interrupted or cancelled | Check whether a mutation ran before retrying |
 
-API failure details on stderr include the server code and request ID. They may
-include retry delay, policy, quota, reset time, and structured details. Keep the
+API failure details on stderr include the server code and the request ID. They
+may also include the retry delay, the rate policy, the requests remaining, the
+rate limit, the window, the reset delay, and structured details. Keep the
 request ID when reporting a problem.
 
 Only exit `6` means the same command may work later. The SDK already retried