@nuxtseo/cli 0.1.2 → 0.1.4

package/README.md

@@ -123,12 +123,14 @@ to stdout and writes the readable recovery message to stderr.
 
 Local outcomes have no server protocol body. With `--json`, commands such as
 bare `nuxtseo`, `config`, `logout`, and `sites use` emit a tagged CLI-owned JSON
-value with `schemaVersion: 1`. Local failures emit `CliError` with a stable code
-and exit code. These tags are separate from protocol envelopes.
+value with `schemaVersion: 1`. `CliHelp` uses `schemaVersion: 2`. Local failures
+emit `CliError` with a stable code and exit code. These tags are separate from
+protocol envelopes.
 
-`--help --json` returns the selected command, global options, arguments, and
-subcommands as `CliHelp`. Option names are strict; an unknown option exits `2`
-before authentication or network work.
+`--help --json` returns the selected command, inherited `globalOptions`,
+positional `arguments`, command-specific `localOptions`, and `subcommands` as
+`CliHelp`. Option names are strict. An unknown option exits `2` before
+authentication or network work.
 
 ## Automation controls
 
@@ -172,6 +174,7 @@ nuxtseo page scan <url>
 nuxtseo performance
 nuxtseo search status
 nuxtseo search analytics <pages|keywords>
+nuxtseo search indexing <summary|urls>
 nuxtseo research overview
 nuxtseo research keywords <topic>
 nuxtseo research serp <keyword>
@@ -189,6 +192,7 @@ performance, research, content, and account setup. The menu prints the direct
 command it runs.
 
 `search status` reads stored connection state. It never waits for Google.
+`search indexing summary` reads retained URL Inspection coverage.
 `research keywords`, `research serp`, and `research rankings` can use the Team
 research allowance. Keyword responses report cache use in `evidence`. SERP and
 ranking responses report `cached: true`. Cached responses use no unit.
@@ -204,6 +208,7 @@ responses.
 | `backlinks recoverable` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
 | `mentions list` | `--limit 1..200` | `--limit 100` |
 | `search analytics` | `--limit 1..100`, `--page >=1` | `--limit 25 --page 1` |
+| `search indexing` | `--limit 1..500`, `--offset >=0` | `--limit 50 --offset 0` |
 | `content briefs list` | `--limit 1..100`, `--offset >=0` | `--limit 25 --offset 0` |
 
 Keep the server order for actions. For another page, pass the next offset or

package/dist/cli.js

@@ -252,6 +252,7 @@ async function interactiveBare(runtime, globals) {
             options: [
                 { value: 'performance', label: 'Performance overview' },
                 { value: 'connection', label: 'Search Console connection' },
+                { value: 'indexing', label: 'Search indexing coverage' },
                 { value: 'pages', label: 'Search Console Pages' },
                 { value: 'keywords', label: 'Search Console queries' },
             ],
@@ -265,7 +266,9 @@ async function interactiveBare(runtime, globals) {
             ? ['performance']
             : task === 'connection'
                 ? ['search', 'status']
-                : ['search', 'analytics', task];
+                : task === 'indexing'
+                    ? ['search', 'indexing', 'summary']
+                    : ['search', 'analytics', task];
         return runInteractiveCommand(command, runtime, globals);
     }
     if (group === 'research') {

package/dist/command-contract.d.ts

@@ -16,12 +16,13 @@ export interface CliHelpArgument {
 }
 export interface CliHelpResponse {
     _tag: 'CliHelp';
-    schemaVersion: 1;
+    schemaVersion: 2;
     cliVersion: string;
     command: string;
     description?: string;
     globalOptions: CliHelpArgument[];
     arguments: CliHelpArgument[];
+    localOptions: CliHelpArgument[];
     subcommands: Array<{
         name: string;
         description?: string;

package/dist/command-contract.js

@@ -54,14 +54,16 @@ function argumentsFor(command) {
 export function describeCommand(root, rawArgs, cliVersion) {
     const resolved = resolveCommand(root, rawArgs.filter(argument => argument !== '--help' && argument !== '-h'));
     const meta = commandMeta(resolved.command);
+    const localArguments = resolved.command === root ? [] : argumentsFor(resolved.command);
     return {
         _tag: 'CliHelp',
-        schemaVersion: 1,
+        schemaVersion: 2,
         cliVersion,
         command: resolved.path.join(' '),
         ...(meta.description === undefined ? {} : { description: meta.description }),
         globalOptions: argumentsFor(root).filter(argument => argument.type !== 'positional'),
-        arguments: resolved.command === root ? [] : argumentsFor(resolved.command),
+        arguments: localArguments.filter(argument => argument.type === 'positional'),
+        localOptions: localArguments.filter(argument => argument.type !== 'positional'),
         subcommands: Object.entries(commandChildren(resolved.command)).flatMap(([name, value]) => {
             const child = childCommand(value);
             if (!child)

package/dist/commands.js

@@ -5,7 +5,7 @@ import { openBrowser } from './browser.js';
 import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
 import { parseAbsolutePageUrl, parseChoice, parseInteger } from './parse.js';
-import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderUsage, } from './render.js';
+import { renderAction, renderActionResolution, renderActions, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDuplicateClusters, renderIndexingDiagnostics, renderKeywordResearch, renderLinkOpportunities, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderResearchOverview, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSites, renderTimeline, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
@@ -447,6 +447,36 @@ async function searchAnalytics(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderSearchAnalytics(value.data));
 }
+async function searchIndexing(runtime, globals, args) {
+    const view = parseChoice(args.view, { name: 'view', choices: ['summary', 'urls'] });
+    if (view._tag === 'Err')
+        return view;
+    const status = args.status === undefined
+        ? ok(undefined)
+        : parseChoice(args.status, { name: '--status', choices: ['indexed', 'not_indexed', 'pending'] });
+    if (status._tag === 'Err')
+        return status;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 500, defaultValue: 50 });
+    if (limit._tag === 'Err')
+        return limit;
+    const offset = parseInteger(args.offset, { name: '--offset', minimum: 0, defaultValue: 0 });
+    if (offset._tag === 'Err')
+        return offset;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Search Console indexing', () => resolved.value.api.client.search.readIndexingDiagnostics({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            view: view.value,
+            issue: args.issue,
+            status: status.value,
+            limit: limit.value,
+            offset: offset.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderIndexingDiagnostics(value.data));
+}
 async function researchOverview(runtime, globals) {
     const resolved = await apiAndSite(runtime, globals);
     if (resolved._tag === 'Err')
@@ -576,6 +606,27 @@ async function auditLinkOpportunities(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderLinkOpportunities(value.data));
 }
+async function timelineEntries(runtime, globals, args) {
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 25 });
+    if (limit._tag === 'Err')
+        return limit;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Timeline', () => resolved.value.api.client.timeline.entries({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            kinds: args.kind,
+            feature: args.feature,
+            severity: args.severity,
+            since: args.since,
+            limit: limit.value,
+            cursor: args.cursor,
+            includeClosed: args.includeClosed,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderTimeline(value.data));
+}
 async function contentBriefList(runtime, globals, args) {
     const status = args.status === undefined
         ? ok(undefined)
@@ -928,6 +979,49 @@ export function createRootCommand(runtime, globals, execution) {
                     sortDir: args['sort-dir'],
                 }), args._, 1)(),
             }),
+            indexing: defineCommand({
+                meta: { name: 'indexing', description: 'Read retained Search Console indexing coverage' },
+                args: {
+                    view: positional('summary-or-urls', 'summary or urls'),
+                    issue: { type: 'string', description: 'Filter URLs by issue type' },
+                    status: { type: 'enum', options: ['indexed', 'not_indexed', 'pending'], description: 'Filter URLs by indexing status' },
+                    limit: { type: 'string', description: 'Maximum URLs, 1 to 500' },
+                    offset: { type: 'string', description: 'Pagination offset' },
+                },
+                run: ({ args }) => capture(execution, () => searchIndexing(runtime, globals, {
+                    view: args.view,
+                    issue: args.issue,
+                    status: args.status,
+                    limit: args.limit,
+                    offset: args.offset,
+                }), args._, 1)(),
+            }),
+        },
+    });
+    const timeline = defineCommand({
+        meta: { name: 'timeline', description: 'Read the Timeline — what changed on the Site' },
+        subCommands: {
+            list: defineCommand({
+                meta: { name: 'list', description: 'List Timeline Entries' },
+                args: {
+                    'kind': { type: 'string', description: 'Comma-separated Timeline Entry kinds, e.g. traffic.dropped,indexing.changed' },
+                    'feature': { type: 'string', description: 'Filter to the kinds registered under this feature' },
+                    'severity': { type: 'string', description: 'Comma-separated severities: info, notable, high' },
+                    'since': { type: 'string', description: 'Only entries at or after this ISO timestamp' },
+                    'limit': { type: 'string', description: 'Maximum Timeline Entries, 1 to 100' },
+                    'cursor': { type: 'string', description: 'Opaque pagination cursor from a previous page' },
+                    'include-closed': { type: 'boolean', description: 'Include closed episodes' },
+                },
+                run: ({ args }) => capture(execution, () => timelineEntries(runtime, globals, {
+                    kind: args.kind,
+                    feature: args.feature,
+                    severity: args.severity,
+                    since: args.since,
+                    limit: args.limit,
+                    cursor: args.cursor,
+                    includeClosed: args['include-closed'],
+                }), args._, 0)(),
+            }),
         },
     });
     return defineCommand({
@@ -994,6 +1088,7 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             research,
             search,
+            timeline,
         },
     });
 }

package/dist/render.d.ts

@@ -3,10 +3,11 @@ import type { ActionList, ActionResolve, ActionShow } from '@nuxtseo/protocol/v1
 import type { AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities } from '@nuxtseo/protocol/v1/audit';
 import type { Mentions, RecoverableBacklinks } from '@nuxtseo/protocol/v1/backlinks';
 import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
-import type { SearchAnalyticsData, SearchStatusData } from '@nuxtseo/protocol/v1/gsc';
+import type { IndexingDiagnosticsData, SearchAnalyticsData, SearchStatusData } from '@nuxtseo/protocol/v1/gsc';
 import type { PageInspect, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
 import type { KeywordResearchData, RankingsResearchData, SerpResearchData, StoredResearchOverview } from '@nuxtseo/protocol/v1/research';
+import type { TimelineEntries } from '@nuxtseo/protocol/v1/timeline';
 export declare function renderSites(response: SitesListResponse, selectedSiteId?: string): string;
 export declare function renderUsage(response: AccountUsageResponse): string;
 export declare function renderActions(data: ActionList): string;
@@ -17,6 +18,7 @@ export declare function renderPageScan(data: PageScan): string;
 export declare function renderPerformance(data: SitePerformanceOverview): string;
 export declare function renderSearchStatus(data: SearchStatusData): string;
 export declare function renderSearchAnalytics(data: SearchAnalyticsData): string;
+export declare function renderIndexingDiagnostics(data: IndexingDiagnosticsData): string;
 export declare function renderResearchOverview(data: StoredResearchOverview): string;
 export declare function renderKeywordResearch(data: KeywordResearchData): string;
 export declare function renderSerpResearch(data: SerpResearchData): string;
@@ -27,5 +29,6 @@ export declare function renderContentBriefCreated(data: ContentBriefCreateData):
 export declare function renderContentDecay(data: AuditContentDecay): string;
 export declare function renderDuplicateClusters(data: AuditDuplicateClusters): string;
 export declare function renderLinkOpportunities(data: AuditLinkOpportunities): string;
+export declare function renderTimeline(data: TimelineEntries): string;
 export declare function renderRecoverableBacklinks(data: RecoverableBacklinks): string;
 export declare function renderMentions(data: Mentions): string;

package/dist/render.js

@@ -151,6 +151,34 @@ export function renderSearchAnalytics(data) {
         ['Rows', 'rows' in data ? data.rows.length : data.type === 'timeseries' ? data.daily.length : 0],
     ]);
 }
+export function renderIndexingDiagnostics(data) {
+    if (data.view === 'summary') {
+        const indexedPercent = data.totalUrls > 0
+            ? `${(data.indexed / data.totalUrls * 100).toFixed(1)}%`
+            : '0.0%';
+        const issues = data.issues
+            .filter(issue => issue.count > 0)
+            .sort((left, right) => right.count - left.count)
+            .map(issue => `${issue.count}  ${issue.label}  ${issue.severity}`);
+        return [
+            fields([
+                ['Known URLs', data.totalUrls],
+                ['Indexed', data.indexed],
+                ['Not indexed', Math.max(0, data.totalUrls - data.indexed)],
+                ['Indexed rate', indexedPercent],
+                ['As of', data.asOf],
+            ]),
+            ...(issues.length > 0 ? ['Issues', ...issues] : []),
+        ].join('\n');
+    }
+    if (data.urls.length === 0)
+        return 'No Search Console indexing URLs match these filters.';
+    return [
+        `Search Console indexing URLs (${data.urls.length} of ${data.total})`,
+        ...data.urls.map(row => `${row.verdict ?? 'unknown'}  ${row.coverageState ?? 'unknown'}\n  ${row.url}`),
+        data.hasMore ? `More URLs available after offset ${data.offset + data.limit}.` : '',
+    ].filter(Boolean).join('\n');
+}
 export function renderResearchOverview(data) {
     const subject = data.subject
         ? fields([
@@ -242,6 +270,18 @@ export function renderLinkOpportunities(data) {
         ...data.rows.map(row => `${row.phrase}\n  From: ${row.sourceUrl}\n  To: ${row.targetUrl}`),
     ].join('\n');
 }
+export function renderTimeline(data) {
+    if (data.entries.length === 0)
+        return 'No Timeline Entries match these filters.';
+    return [
+        `Timeline (${data.entries.length})`,
+        ...data.entries.map((entry) => {
+            const label = typeof entry.rendered?.label === 'string' ? entry.rendered.label : entry.kind;
+            return `${entry.occurredAt}  ${entry.severity ?? 'unrated'}  ${entry.kind}\n  ${label}`;
+        }),
+        data.nextCursor ? `More Timeline Entries available — pass --cursor ${JSON.stringify(data.nextCursor)}.` : '',
+    ].filter(Boolean).join('\n');
+}
 export function renderRecoverableBacklinks(data) {
     if (data.items.length === 0)
         return 'No recoverable Backlinks. Every stored inbound link resolves.';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -34,7 +34,7 @@
     "@clack/prompts": "^1.7.0",
     "citty": "^0.2.2",
     "pathe": "^2.0.3",
-    "@nuxtseo/sdk": "^0.1.2"
+    "@nuxtseo/sdk": "^0.1.4"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.3.0"
@@ -44,7 +44,7 @@
     "@types/node": "^26.2.0",
     "publint": "^0.3.24",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
-    "@nuxtseo/protocol": "0.1.2"
+    "@nuxtseo/protocol": "0.1.4"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -26,6 +26,7 @@ report `cached`.
 
 `search status` reads stored connection state. It never waits for Google.
 `search analytics` reads Search Console rows through the public API.
+`search indexing` reads retained URL Inspection coverage through the public API.
 
 ## Get the binary
 
@@ -115,6 +116,7 @@ handling failures, read [CLI protocol](references/protocol.md).
 | `performance` | Site performance overview | Medians for perf, a11y, SEO, LCP, TBT, CLS |
 | `search status` | Stored Search Console connection | Provider free |
 | `search analytics <pages\|keywords>` | Search Console Page or query rows | `--period`, `--limit`, `--page`, `--search` |
+| `search indexing <summary\|urls>` | Retained URL Inspection coverage | `summary` returns indexed counts; `urls` supports `--issue`, `--status`, `--limit`, `--offset` |
 | `research overview` | Stored Site and competitor research | Metrics, history, gaps, and quick wins |
 | `research keywords <topic>` | Live keyword ideas | Volume, difficulty, intent, and cost data |
 | `research serp <keyword>` | Live SERP snapshot | Results, features, and fetch time |
@@ -130,11 +132,11 @@ handling failures, read [CLI protocol](references/protocol.md).
 `page inspect` and `page scan` take an absolute URL, for example
 `https://example.com/about`.
 
-`--help --json` returns a `CliHelp` value for one command level: its
-`arguments`, the inherited `globalOptions`, and its `subcommands` as names and
-descriptions only. To learn a subcommand's own flags, ask it directly, for
-example `nuxtseo actions list --help --json`. Use this instead of guessing a
-flag, and prefer the table above for anything it already answers.
+`--help --json` returns a `CliHelp` value for one command level. It separates
+positional `arguments`, command-specific `localOptions`, inherited
+`globalOptions`, and `subcommands`. To learn a subcommand's own flags, ask it
+directly, for example `nuxtseo actions list --help --json`. Use this instead of
+guessing a flag, and prefer the table above for anything it already answers.
 
 ## The triage loop
 

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 |
 | --- | --- |