@nuxtseo/cli 0.1.4 → 0.2.0

package/README.md

@@ -71,9 +71,14 @@ Outside an interactive terminal, `login` reads a token from stdin instead of
 pairing, so CI keeps working. Tokens are never accepted as positional arguments
 or options.
 
-The CLI validates the token with a public Site read, then stores it in the OS
-keychain through optional `@napi-rs/keyring`. When keychain support is
-unavailable, it warns on stderr and uses `~/.nuxtseo/auth.json` with mode `0600`.
+The CLI validates the token with `GET /api/v1/account/token`, which reports the
+Team, the role, the granted scopes, and the expiry without reading a Site. It
+then stores the token in the OS keychain through optional `@napi-rs/keyring`.
+When keychain support is unavailable, it warns on stderr and uses
+`~/.nuxtseo/auth.json` with mode `0600`.
+
+`nuxtseo whoami` reads the same operation, so an agent learns about a missing
+scope before the request that needs it.
 
 `nuxtseo logout` removes the local credential. Revoke the token from the
 NuxtSEO dashboard when it must stop working everywhere. An environment token
@@ -164,75 +169,151 @@ nuxtseo config
 nuxtseo sites list
 nuxtseo sites use <site-id>
 nuxtseo usage
+nuxtseo status
 nuxtseo actions list
 nuxtseo actions show <action-id>
 nuxtseo actions resolve <action-id>
+nuxtseo actions dismiss <action-id>
+nuxtseo backlinks summary
+nuxtseo backlinks referring-domains
+nuxtseo backlinks anchors
+nuxtseo backlinks history
 nuxtseo backlinks recoverable
 nuxtseo mentions list
 nuxtseo page inspect <url>
+nuxtseo page issues
 nuxtseo page scan <url>
 nuxtseo performance
+nuxtseo vitals summary
+nuxtseo vitals trend
+nuxtseo vitals findings
+nuxtseo scans list
+nuxtseo scans show <scan-id>
+nuxtseo scans pages
+nuxtseo annotations list
+nuxtseo annotations create
+nuxtseo annotations update <annotation-id>
+nuxtseo annotations delete <annotation-id>
+nuxtseo analytics <view>
 nuxtseo search status
-nuxtseo search analytics <pages|keywords>
+nuxtseo search analytics <view>
 nuxtseo search indexing <summary|urls>
+nuxtseo search cohorts
+nuxtseo search index-history
+nuxtseo search inspect <url>
+nuxtseo sitemaps list
+nuxtseo sitemaps urls
+nuxtseo sitemaps submit <sitemap-url>
+nuxtseo sitemaps delete <sitemap-url>
 nuxtseo research overview
+nuxtseo research domain-traffic <domain>
+nuxtseo research domain-availability <domains>
 nuxtseo research keywords <topic>
 nuxtseo research serp <keyword>
 nuxtseo research rankings <domain>
+nuxtseo audit changes
 nuxtseo audit link-opportunities
+nuxtseo audit link-structure
 nuxtseo audit content-decay
 nuxtseo audit duplicates
 nuxtseo content briefs list
 nuxtseo content briefs show <brief-id>
 nuxtseo content briefs create <keyword>
+nuxtseo timeline list
+nuxtseo skill install
 ```
 
+`search analytics` takes `pages`, `keywords`, `countries`, `devices`,
+`timeseries`, `page-detail`, `keyword-detail`, or `analysis`. `page-detail`
+needs `--page-url`, `keyword-detail` needs `--keyword`, and `analysis` needs
+`--preset`. The `brand-only` and `non-brand` presets also need `--brand-terms`.
+The CLI refuses a missing argument before it sends a request.
+
+`analytics` takes `performance`, `top-pages`, `source-medium`, `key-events`,
+`countries`, `devices`, or `dimension`. The `dimension` view needs
+`--dimension`.
+
 Run bare `nuxtseo` in a terminal for a task-based menu. It groups Site fixes,
 performance, research, content, and account setup. The menu prints the direct
 command it runs.
 
+`performance` reads the stored Lighthouse lab overview. Real-user field data is
+a different dataset: `vitals summary` and `vitals trend` read CrUX field p75,
+and `vitals findings` names the DOM element behind each failing vital.
+`status` reads the Site assessment: the verdict, the one ranked Next Action, and
+what changed. Start there. `status`, `page issues` and `search cohorts` refuse
+with exit `4` or `5` on an archived or paused Site.
+The four live `backlinks` reads need the Site to have a URL. Without one they
+exit `2`, and retrying will not help; set the Site URL first.
+`search cohorts` returns two lists. Only `established` is proven; `ranked` is
+ordered by raw rate with no significance test and is leads only.
+`backlinks summary`, `backlinks referring-domains`, `backlinks anchors`,
+`backlinks history`, `research domain-traffic` and `research domain-availability`
+can use the Team research limit. Each response reports
+cache use in `evidence`; a cached response spends nothing. `backlinks recoverable`
+reads retained rows and spends nothing.
 `search status` reads stored connection state. It never waits for Google.
 `search indexing summary` reads retained URL Inspection coverage.
+`search index-history` dates an indexing change against known releases.
+`search inspect <url>` reads Google's own verdict for one URL.
+`page inspect <url>` reads the NuxtSEO observation store for the same URL.
 `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.
-
-The CLI fetches one page per invocation. It does not auto-page or merge
-responses.
-
-| Command | Paging inputs | Default |
-| --- | --- | --- |
-| `actions list` | `--limit 1..25`, `--offset >=0` | `--limit 10 --offset 0` |
-| `actions show` | `--group-id`, `--cursor`, `--limit 1..100` | `--limit 50` |
-| `page inspect` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
-| `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` |
+research limit. Keyword responses report cache use in `evidence`. SERP and
+ranking responses report `cached: true`. A cached response spends nothing.
+
+The CLI fetches one page per invocation by default. It never merges responses.
+
+| Command | Paging inputs | Default | `--all` |
+| --- | --- | --- | --- |
+| `actions list` | `--limit 1..25`, `--offset >=0` | `--limit 10 --offset 0` | yes |
+| `actions show` | `--group-id`, `--cursor`, `--limit 1..100` | `--limit 50` | no |
+| `page inspect` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` | yes |
+| `backlinks recoverable` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` | yes |
+| `backlinks referring-domains` | `--limit 1..1000` | `--limit 100` | no |
+| `backlinks anchors` | `--limit 1..1000` | `--limit 100` | no |
+| `vitals findings` | `--limit 1..50`, `--offset >=0` | `--limit 20 --offset 0` | yes |
+| `page issues` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` | yes |
+| `scans list` | `--limit 1..100` | `--limit 25` | no |
+| `search cohorts` | `--limit 1..50`, `--min-pages 1..500` | `--limit 12 --min-pages 5` | no |
+| `mentions list` | `--limit 1..200` | `--limit 100` | no |
+| `search analytics` | `--limit 1..100`, `--page >=1` | `--limit 25 --page 1` | row views only |
+| `search indexing` | `--limit 1..500`, `--offset >=0` | `--limit 50 --offset 0` | `urls` view only |
+| `sitemaps urls` | `--cursor`, `--limit 1..1000` | `--limit 500` | yes |
+| `content briefs list` | `--limit 1..100`, `--offset >=0` | `--limit 25 --offset 0` | yes |
+| `timeline list` | `--kind`, `--feature`, `--severity`, `--since`, `--cursor`, `--limit 1..100` | `--limit 25` | no |
 
 Keep the server order for actions. For another page, pass the next offset or
 cursor reported by the response. A cursor is opaque; do not edit or infer it.
 
-## Coding agents
+### `--all`
 
-The package ships an agent skill that teaches coding agents how to drive the
-CLI. Copy it into a global skill directory after installation.
+`--all` repeats the same operation until the server reports no more pages. It
+writes one complete envelope per page, newline delimited. The CLI never merges,
+unwraps, or re-ranks a page. Read the stream one JSON value per line.
 
-Claude Code:
+The loop stops after 50 requests. If pages remain at that point, the CLI exits
+`9` and stderr names the exact argument that resumes the read, for example
+`--offset 50`. Exit `9` is a stop, never an end of data.
 
-```sh
-mkdir -p ~/.claude/skills
-cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.claude/skills/
-```
+`--all` covers the Search Console views the server pages: `pages`, `keywords`,
+`countries`, `devices`, and `analysis`, plus the `urls` indexing view. Every
+other view returns one payload, so the CLI refuses `--all` there with exit `2`.
 
-Codex:
+## Coding agents
+
+The package ships an agent skill that teaches coding agents how to drive the
+CLI. Install it with the CLI itself; a global install has no local
+`node_modules` to copy from.
 
 ```sh
-mkdir -p ~/.codex/skills
-cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.codex/skills/
+nuxtseo skill install                 # ~/.claude/skills/nuxtseo-cli
+nuxtseo skill install --agent codex   # ~/.codex/skills/nuxtseo-cli
+nuxtseo skill install --target ./.claude/skills
 ```
 
+The command reports the destination it wrote. With `--json` it emits
+`CliSkillInstall` carrying the source and the destination.
+
 The skill covers the JSON contract, Site selection, paging, mutation consent,
 and what to do for each exit code.
 
@@ -248,6 +329,7 @@ and what to do for each exit code.
 | `6` | Rate, quota, provider, or request timeout | Read retry metadata on stderr and retry later |
 | `7` | Local state, network, contract, or infrastructure failure | Fix the named path or network issue; keep the request ID |
 | `8` | Resource or accessible Site not found | Run `sites list`, then `sites use` or pass `--site` |
+| `9` | `--all` reached its 50 request cap | Resume with the argument stderr names |
 | `130` | Interrupted or cancelled | Confirm no mutation result before retrying |
 
 The CLI prints the exact server error code. When available, stderr also includes

package/dist/api.js

@@ -1,6 +1,7 @@
 import { createBearerTransport, createPublicV1Client } from '@nuxtseo/sdk';
 import { EXIT_CODE, fail, ok } from './failures.js';
 import { readConfig, resolveApiUrl, resolveCredential } from './state/index.js';
+import { VERSION } from './version.js';
 export function fromStateError(error) {
     const exitCode = error._tag === 'InvalidCredential'
         ? EXIT_CODE.authentication
@@ -16,7 +17,12 @@ export function fromStateError(error) {
 }
 export function createApiClient(apiUrl, token) {
     return createPublicV1Client({
-        transport: createBearerTransport({ baseUrl: apiUrl, token }),
+        transport: createBearerTransport({
+            baseUrl: apiUrl,
+            token,
+            // ADR-0121: agent_connected classifies the access surface by this prefix.
+            headers: { 'user-agent': `nuxtseo-cli/${VERSION}` },
+        }),
     });
 }
 export async function loadApiContext(runtime, globals) {

package/dist/cli.js

@@ -208,7 +208,7 @@ async function interactiveBare(runtime, globals) {
         message: 'Choose a task',
         options: [
             ...(!auth.value.authenticated ? [{ value: 'login', label: 'Log in', hint: 'Team API token' }] : []),
-            { value: 'fix', label: 'Fix my Site', hint: 'Issues, Pages, and scans' },
+            { value: 'fix', label: 'Fix my Site', hint: 'Issues, Pages, and Scans' },
             { value: 'performance', label: 'Understand performance', hint: 'Performance and Search Console' },
             { value: 'research', label: 'Research growth', hint: 'Keywords, SERPs, and competitors' },
             { value: 'content', label: 'Plan content', hint: 'Briefs, decay, and duplicates' },
@@ -227,7 +227,10 @@ async function interactiveBare(runtime, globals) {
         const task = await prompts.select({
             message: 'Fix my Site',
             options: [
+                { value: 'status', label: 'What should I fix first?', hint: 'assessment and next action' },
                 { value: 'actions', label: 'Issues and opportunities' },
+                { value: 'page-issues', label: 'Raw Page Issue rows for one issue type' },
+                { value: 'changes', label: 'What the last crawl changed' },
                 { value: 'inspect', label: 'Inspect a Page' },
                 { value: 'scan', label: 'Scan a Page' },
                 { value: 'backlinks', label: 'Recover broken Backlinks' },
@@ -244,15 +247,30 @@ async function interactiveBare(runtime, globals) {
                 ? url
                 : runInteractiveCommand(['page', task, url.value], runtime, globals);
         }
-        return runInteractiveCommand(task === 'actions' ? ['actions', 'list'] : ['backlinks', 'recoverable'], runtime, globals);
+        const command = task === 'actions'
+            ? ['actions', 'list']
+            : task === 'changes'
+                ? ['audit', 'changes']
+                : task === 'status'
+                    ? ['status']
+                    : task === 'page-issues'
+                        ? ['page', 'issues', '--source', 'crawl', '--issue', 'broken-internal-links']
+                        : ['backlinks', 'recoverable'];
+        return runInteractiveCommand(command, runtime, globals);
     }
     if (group === 'performance') {
         const task = await prompts.select({
             message: 'Understand performance',
             options: [
-                { value: 'performance', label: 'Performance overview' },
+                { value: 'performance', label: 'Performance overview', hint: 'stored Lighthouse lab Scans' },
+                { value: 'vitals', label: 'Field Core Web Vitals', hint: 'CrUX real-user p75' },
+                { value: 'findings', label: 'What to fix for Core Web Vitals', hint: 'element and fix prompt' },
+                { value: 'scans', label: 'Lighthouse Scans', hint: 'retained lab Scans' },
+                { value: 'cohorts', label: 'Indexing by route family', hint: 'which template Google declines' },
                 { value: 'connection', label: 'Search Console connection' },
                 { value: 'indexing', label: 'Search indexing coverage' },
+                { value: 'sitemaps', label: 'Search Console sitemaps' },
+                { value: 'traffic', label: 'Web Analytics' },
                 { value: 'pages', label: 'Search Console Pages' },
                 { value: 'keywords', label: 'Search Console queries' },
             ],
@@ -264,11 +282,23 @@ async function interactiveBare(runtime, globals) {
             return ok(undefined);
         const command = task === 'performance'
             ? ['performance']
-            : task === 'connection'
-                ? ['search', 'status']
-                : task === 'indexing'
-                    ? ['search', 'indexing', 'summary']
-                    : ['search', 'analytics', task];
+            : task === 'vitals'
+                ? ['vitals', 'summary']
+                : task === 'findings'
+                    ? ['vitals', 'findings']
+                    : task === 'scans'
+                        ? ['scans', 'list']
+                        : task === 'cohorts'
+                            ? ['search', 'cohorts']
+                            : task === 'connection'
+                                ? ['search', 'status']
+                                : task === 'indexing'
+                                    ? ['search', 'indexing', 'summary']
+                                    : task === 'sitemaps'
+                                        ? ['sitemaps', 'list']
+                                        : task === 'traffic'
+                                            ? ['analytics', 'performance']
+                                            : ['search', 'analytics', task];
         return runInteractiveCommand(command, runtime, globals);
     }
     if (group === 'research') {
@@ -276,10 +306,13 @@ async function interactiveBare(runtime, globals) {
             message: 'Research growth',
             options: [
                 { value: 'overview', label: 'Site and competitors', hint: 'stored data' },
-                { value: 'keywords', label: 'Keyword ideas', hint: 'uses live research allowance' },
-                { value: 'serp', label: 'SERP analysis', hint: 'uses live research allowance' },
-                { value: 'rankings', label: 'Domain rankings', hint: 'uses live research allowance' },
+                { value: 'keywords', label: 'Keyword ideas', hint: 'uses the live research limit' },
+                { value: 'serp', label: 'SERP analysis', hint: 'uses the live research limit' },
+                { value: 'rankings', label: 'Domain rankings', hint: 'uses the live research limit' },
                 { value: 'links', label: 'Link opportunities', hint: 'stored data' },
+                { value: 'structure', label: 'Link structure', hint: 'stored data' },
+                { value: 'backlinks', label: 'Backlink profile', hint: 'uses the live research limit' },
+                { value: 'domain', label: 'Any domain traffic estimate', hint: 'uses the live research limit' },
             ],
             input: runtime.input,
             output: runtime.error,
@@ -291,6 +324,20 @@ async function interactiveBare(runtime, globals) {
             return runInteractiveCommand(['research', 'overview'], runtime, globals);
         if (task === 'links')
             return runInteractiveCommand(['audit', 'link-opportunities'], runtime, globals);
+        if (task === 'structure')
+            return runInteractiveCommand(['audit', 'link-structure'], runtime, globals);
+        if (task === 'backlinks')
+            return runInteractiveCommand(['backlinks', 'summary'], runtime, globals);
+        if (task === 'domain') {
+            const domain = await promptTextValue(runtime, {
+                message: 'Which domain?',
+                placeholder: 'example.com',
+                label: 'Domain',
+            });
+            if (domain._tag === 'Err')
+                return domain;
+            return runInteractiveCommand(['research', 'domain-traffic', domain.value], runtime, globals);
+        }
         const label = task === 'rankings' ? 'Domain' : 'Keyword';
         const value = await promptTextValue(runtime, {
             message: task === 'rankings' ? 'Which domain?' : 'Which keyword or topic?',
@@ -309,6 +356,7 @@ async function interactiveBare(runtime, globals) {
                 { value: 'create', label: 'Create a Content Brief' },
                 { value: 'decay', label: 'Content decay' },
                 { value: 'duplicates', label: 'Duplicate clusters' },
+                { value: 'annotations', label: 'Chart annotations', hint: 'mark what you shipped' },
             ],
             input: runtime.input,
             output: runtime.error,
@@ -322,6 +370,8 @@ async function interactiveBare(runtime, globals) {
             return runInteractiveCommand(['audit', 'content-decay'], runtime, globals);
         if (task === 'duplicates')
             return runInteractiveCommand(['audit', 'duplicates'], runtime, globals);
+        if (task === 'annotations')
+            return runInteractiveCommand(['annotations', 'list'], runtime, globals);
         const keyword = await promptTextValue(runtime, {
             message: 'Which target keyword?',
             placeholder: 'nuxt seo',
@@ -336,6 +386,7 @@ async function interactiveBare(runtime, globals) {
         options: [
             { value: 'site', label: 'Switch Site', hint: config.value.siteId ?? 'none selected' },
             { value: 'usage', label: 'Account usage' },
+            { value: 'whoami', label: 'Credential and scopes' },
             { value: 'config', label: 'Configuration' },
             { value: 'logout', label: 'Log out' },
         ],

package/dist/command-contract.js

@@ -82,7 +82,9 @@ function optionName(argument) {
 export function validateCommandOptions(root, rawArgs) {
     const resolved = resolveCommand(root, rawArgs);
     const definitions = commandArgs(resolved.command);
+    const positionals = Object.values(definitions).filter(definition => definition.type === 'positional');
     const aliases = new Map();
+    let positionalIndex = 0;
     for (const definition of Object.values(definitions)) {
         const alias = 'alias' in definition ? definition.alias : undefined;
         const names = alias === undefined
@@ -116,7 +118,15 @@ export function validateCommandOptions(root, rawArgs) {
                 return fail(EXIT_CODE.invalidInput, `invalid_cli_input: Unknown option ${JSON.stringify(token)}.`);
             if (definition.type !== 'boolean' && !resolved.remaining[index + 1]?.startsWith('-'))
                 index++;
+            continue;
+        }
+        if (positionalIndex < positionals.length) {
+            positionalIndex++;
+            continue;
         }
+        if (Object.keys(commandChildren(resolved.command)).length > 0)
+            return fail(EXIT_CODE.invalidInput, `invalid_cli_input: Unknown command ${token}`);
+        return fail(EXIT_CODE.invalidInput, `invalid_cli_input: Unexpected argument ${JSON.stringify(token)}.`);
     }
     return ok(undefined);
 }

package/dist/commands.d.ts

@@ -5,4 +5,23 @@ import type { CliRuntime } from './runtime.js';
 export interface CommandExecution {
     result: CliResult<void> | null;
 }
+/**
+ * `--all` request cap. One page per request stays the default. `--all` repeats
+ * the same operation and writes one complete envelope per page, so nothing is
+ * merged or renamed. The cap bounds an unattended loop; reaching it exits 9 and
+ * names the resume argument, so a caller never mistakes a stop for an end.
+ */
+export declare const ALL_PAGES_REQUEST_CAP = 50;
+export interface PagePosition {
+    offset?: number;
+    page?: number;
+    cursor?: string;
+}
+export type NextPage = {
+    _tag: 'More';
+    position: PagePosition;
+    resume: string;
+} | {
+    _tag: 'Done';
+};
 export declare function createRootCommand(runtime: CliRuntime, globals: GlobalOptions, execution: CommandExecution): CommandDef<any>;