@nuxtseo/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,8 @@
 # NuxtSEO CLI
 
 Use NuxtSEO public Site operations from a terminal, script, or coding agent.
-The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP,
-private routes, or providers.
+The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP or
+private routes. Live research uses declared public API operations.
 
 ## Install
 
@@ -148,7 +148,8 @@ Agent controls:
 | `--no-input` | Disable every prompt even when stdin and stdout are TTYs |
 | `--timeout-ms <milliseconds>` | Apply one deadline to Site resolution, SDK retries, and the operation; default `30000`, maximum `300000` |
 
-Request timeouts return `CliError` code `request_timeout` and exit `6`.
+Request timeouts return `CliError` code `request_timeout` and exit `6`. The
+error prints an exact retry command with a longer deadline.
 `SIGINT` and `SIGTERM` abort the active request and return exit `130`.
 
 ## Commands and paging
@@ -170,8 +171,28 @@ nuxtseo page inspect <url>
 nuxtseo page scan <url>
 nuxtseo performance
 nuxtseo search status
+nuxtseo search analytics <pages|keywords>
+nuxtseo research overview
+nuxtseo research keywords <topic>
+nuxtseo research serp <keyword>
+nuxtseo research rankings <domain>
+nuxtseo audit link-opportunities
+nuxtseo audit content-decay
+nuxtseo audit duplicates
+nuxtseo content briefs list
+nuxtseo content briefs show <brief-id>
+nuxtseo content briefs create <keyword>
 ```
 
+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.
+
+`search status` reads stored connection state. It never waits for Google.
+`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.
 
@@ -182,18 +203,29 @@ responses.
 | `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` |
+| `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
 cursor reported by the response. A cursor is opaque; do not edit or infer it.
 
 ## Coding agents
 
-The package ships an agent skill that teaches Claude Code how to drive the CLI.
-Copy it into a project after install:
+The package ships an agent skill that teaches coding agents how to drive the
+CLI. Copy it into a global skill directory after installation.
+
+Claude Code:
+
+```sh
+mkdir -p ~/.claude/skills
+cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.claude/skills/
+```
+
+Codex:
 
 ```sh
-mkdir -p .claude/skills
-cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli .claude/skills/
+mkdir -p ~/.codex/skills
+cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli ~/.codex/skills/
 ```
 
 The skill covers the JSON contract, Site selection, paging, mutation consent,

package/dist/cli.js

@@ -135,6 +135,45 @@ async function promptPageUrl(runtime, action) {
         ? fail(EXIT_CODE.interrupted, `interrupted: ${action} cancelled.`)
         : ok(url);
 }
+async function promptTextValue(runtime, options) {
+    const value = await prompts.text({
+        message: options.message,
+        placeholder: options.placeholder,
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+        validate: input => typeof input === 'string' && input.trim().length > 1
+            ? undefined
+            : `${options.label} is required.`,
+    });
+    return prompts.isCancel(value)
+        ? fail(EXIT_CODE.interrupted, `interrupted: ${options.label} entry cancelled.`)
+        : ok(value.trim());
+}
+function displayCommand(args) {
+    return `nuxtseo ${args.map(argument => /\s/.test(argument) ? JSON.stringify(argument) : argument).join(' ')}`;
+}
+function timeoutRetryFailure(failure, rawArgs, timeoutMs) {
+    if (failure.code !== 'request_timeout')
+        return failure;
+    const args = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        const argument = rawArgs[index];
+        if (argument === '--timeout-ms') {
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--timeout-ms='))
+            continue;
+        args.push(argument);
+    }
+    args.push('--timeout-ms', String(Math.min(timeoutMs * 2, 300_000)));
+    return { ...failure, message: `${failure.message}\nRetry: ${displayCommand(args)}` };
+}
+async function runInteractiveCommand(args, runtime, globals) {
+    writeDiagnostic(runtime, `Command: ${displayCommand(args)}`);
+    return runExplicit(args, runtime, globals);
+}
 async function interactiveBare(runtime, globals) {
     const [auth, apiUrl, config] = await Promise.all([
         getCredentialStatus({ env: runtime.env, paths: runtime.paths }),
@@ -153,43 +192,147 @@ async function interactiveBare(runtime, globals) {
         `API: ${apiUrl.value.apiUrl}`,
         `Current Site: ${config.value.siteId ?? 'none'}`,
     ].join('\n'), 'Status', { input: runtime.input, output: runtime.error });
-    const selected = await prompts.select({
-        message: 'What would you like to do?',
+    const group = await prompts.select({
+        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: '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' },
+            { value: 'account', label: 'Account and setup', hint: config.value.siteId ?? 'no Site selected' },
+            { value: 'exit', label: 'Exit' },
+        ],
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+    });
+    if (prompts.isCancel(group) || group === 'exit')
+        return ok(undefined);
+    if (group === 'login')
+        return runInteractiveCommand(['login'], runtime, globals);
+    if (group === 'fix') {
+        const task = await prompts.select({
+            message: 'Fix my Site',
+            options: [
+                { value: 'actions', label: 'Issues and opportunities' },
+                { value: 'inspect', label: 'Inspect a Page' },
+                { value: 'scan', label: 'Scan a Page' },
+                { value: 'backlinks', label: 'Recover broken Backlinks' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'inspect' || task === 'scan') {
+            const url = await promptPageUrl(runtime, task === 'inspect' ? 'Inspect' : 'Scan');
+            return url._tag === 'Err'
+                ? url
+                : runInteractiveCommand(['page', task, url.value], runtime, globals);
+        }
+        return runInteractiveCommand(task === 'actions' ? ['actions', 'list'] : ['backlinks', 'recoverable'], runtime, globals);
+    }
+    if (group === 'performance') {
+        const task = await prompts.select({
+            message: 'Understand performance',
+            options: [
+                { value: 'performance', label: 'Performance overview' },
+                { value: 'connection', label: 'Search Console connection' },
+                { value: 'pages', label: 'Search Console Pages' },
+                { value: 'keywords', label: 'Search Console queries' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        const command = task === 'performance'
+            ? ['performance']
+            : task === 'connection'
+                ? ['search', 'status']
+                : ['search', 'analytics', task];
+        return runInteractiveCommand(command, runtime, globals);
+    }
+    if (group === 'research') {
+        const task = await prompts.select({
+            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: 'links', label: 'Link opportunities', hint: 'stored data' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'overview')
+            return runInteractiveCommand(['research', 'overview'], runtime, globals);
+        if (task === 'links')
+            return runInteractiveCommand(['audit', 'link-opportunities'], runtime, globals);
+        const label = task === 'rankings' ? 'Domain' : 'Keyword';
+        const value = await promptTextValue(runtime, {
+            message: task === 'rankings' ? 'Which domain?' : 'Which keyword or topic?',
+            placeholder: task === 'rankings' ? 'example.com' : 'nuxt seo',
+            label,
+        });
+        if (value._tag === 'Err')
+            return value;
+        return runInteractiveCommand(['research', task, value.value], runtime, globals);
+    }
+    if (group === 'content') {
+        const task = await prompts.select({
+            message: 'Plan content',
+            options: [
+                { value: 'briefs', label: 'Content Briefs' },
+                { value: 'create', label: 'Create a Content Brief' },
+                { value: 'decay', label: 'Content decay' },
+                { value: 'duplicates', label: 'Duplicate clusters' },
+            ],
+            input: runtime.input,
+            output: runtime.error,
+            signal: runtime.signal,
+        });
+        if (prompts.isCancel(task))
+            return ok(undefined);
+        if (task === 'briefs')
+            return runInteractiveCommand(['content', 'briefs', 'list'], runtime, globals);
+        if (task === 'decay')
+            return runInteractiveCommand(['audit', 'content-decay'], runtime, globals);
+        if (task === 'duplicates')
+            return runInteractiveCommand(['audit', 'duplicates'], runtime, globals);
+        const keyword = await promptTextValue(runtime, {
+            message: 'Which target keyword?',
+            placeholder: 'nuxt seo',
+            label: 'Keyword',
+        });
+        return keyword._tag === 'Err'
+            ? keyword
+            : runInteractiveCommand(['content', 'briefs', 'create', keyword.value], runtime, globals);
+    }
+    const task = await prompts.select({
+        message: 'Account and setup',
+        options: [
             { value: 'site', label: 'Switch Site', hint: config.value.siteId ?? 'none selected' },
-            { value: 'actions', label: 'Next actions' },
-            { value: 'inspect', label: 'Inspect a Page' },
-            { value: 'scan', label: 'Scan a Page' },
-            { value: 'performance', label: 'Performance overview' },
-            { value: 'search', label: 'Search Console status' },
             { value: 'usage', label: 'Account usage' },
             { value: 'config', label: 'Configuration' },
-            { value: 'exit', label: 'Exit' },
+            { value: 'logout', label: 'Log out' },
         ],
         input: runtime.input,
         output: runtime.error,
         signal: runtime.signal,
     });
-    if (prompts.isCancel(selected) || selected === 'exit')
+    if (prompts.isCancel(task))
         return ok(undefined);
-    if (selected === 'site')
+    if (task === 'site')
         return switchSite(runtime, globals);
-    if (selected === 'inspect' || selected === 'scan') {
-        const url = await promptPageUrl(runtime, selected === 'inspect' ? 'Inspect' : 'Scan');
-        return url._tag === 'Err'
-            ? url
-            : runExplicit(['page', selected, url.value], runtime, globals);
-    }
-    const commands = {
-        login: ['login'],
-        actions: ['actions', 'list'],
-        performance: ['performance'],
-        search: ['search', 'status'],
-        usage: ['usage'],
-        config: ['config'],
-    };
-    return runExplicit(commands[selected], runtime, globals);
+    return runInteractiveCommand([task], runtime, globals);
 }
 export async function runCli(rawArgs, runtime) {
     const jsonRequested = rawArgs.includes('--json');
@@ -204,6 +347,7 @@ export async function runCli(rawArgs, runtime) {
             runtime.requestSignal,
             AbortSignal.timeout(globals.timeoutMs),
         ]),
+        requestTimeoutMs: globals.timeoutMs,
     };
     if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
         if (globals.json)
@@ -228,5 +372,7 @@ export async function runCli(rawArgs, runtime) {
             ? await interactiveBare(effectiveRuntime, globals)
             : await nonInteractiveBare(effectiveRuntime, globals)
         : await runExplicit(args, effectiveRuntime, globals);
-    return result._tag === 'Ok' ? EXIT_CODE.success : report(effectiveRuntime, result.error, globals.json);
+    return result._tag === 'Ok'
+        ? EXIT_CODE.success
+        : report(effectiveRuntime, timeoutRetryFailure(result.error, rawArgs, globals.timeoutMs), globals.json);
 }

package/dist/commands.js

@@ -4,8 +4,8 @@ import { createApiClient, fromStateError, loadApiContext } from './api.js';
 import { openBrowser } from './browser.js';
 import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
-import { parseAbsolutePageUrl, parseInteger } from './parse.js';
-import { renderAction, renderActionResolution, renderActions, renderMentions, renderPageInspection, renderPageScan, renderPerformance, renderRecoverableBacklinks, renderSearchStatus, renderSites, renderUsage, } from './render.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 { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
@@ -23,7 +23,10 @@ async function withSpinner(runtime, message, task) {
     const spinner = runtime.interactive
         ? prompts.spinner({ output: runtime.error, signal: runtime.signal })
         : null;
-    spinner?.start(message);
+    const deadline = runtime.requestTimeoutMs === undefined
+        ? ''
+        : `, ${Math.ceil(runtime.requestTimeoutMs / 1_000)}s limit`;
+    spinner?.start(`${message}${deadline}`);
     return task().then((result) => {
         spinner?.stop();
         return result;
@@ -408,6 +411,224 @@ async function searchStatus(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderSearchStatus(value.data));
 }
+async function searchAnalytics(runtime, globals, args) {
+    const view = parseChoice(args.view, { name: 'view', choices: ['pages', 'keywords'] });
+    if (view._tag === 'Err')
+        return view;
+    const period = parseChoice(args.period, { name: '--period', choices: ['7d', '28d', '3m', '6m', '12m'], defaultValue: '28d' });
+    if (period._tag === 'Err')
+        return period;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 25 });
+    if (limit._tag === 'Err')
+        return limit;
+    const page = parseInteger(args.page, { name: '--page', minimum: 1, defaultValue: 1 });
+    if (page._tag === 'Err')
+        return page;
+    const sort = parseChoice(args.sort, { name: '--sort', choices: ['clicks', 'impressions', 'ctr', 'position'], defaultValue: 'clicks' });
+    if (sort._tag === 'Err')
+        return sort;
+    const sortDir = parseChoice(args.sortDir, { name: '--sort-dir', choices: ['asc', 'desc'], defaultValue: 'desc' });
+    if (sortDir._tag === 'Err')
+        return sortDir;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Search Console rows', () => resolved.value.api.client.search.queryAnalytics({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            view: view.value,
+            period: period.value,
+            limit: limit.value,
+            page: page.value,
+            search: args.search,
+            sort: sort.value,
+            sortDir: sortDir.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderSearchAnalytics(value.data));
+}
+async function researchOverview(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading stored research', () => resolved.value.api.client.research.overview({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderResearchOverview(value.data));
+}
+async function researchKeywordIdeas(runtime, globals, args) {
+    const minVolume = parseInteger(args.minVolume, { name: '--min-volume', minimum: 0, defaultValue: 10 });
+    if (minVolume._tag === 'Err')
+        return minVolume;
+    const maxVolume = parseInteger(args.maxVolume, { name: '--max-volume', minimum: 0, defaultValue: 10_000 });
+    if (maxVolume._tag === 'Err')
+        return maxVolume;
+    const minDifficulty = parseInteger(args.minDifficulty, { name: '--min-difficulty', minimum: 0, maximum: 100, defaultValue: 0 });
+    if (minDifficulty._tag === 'Err')
+        return minDifficulty;
+    const maxDifficulty = parseInteger(args.maxDifficulty, { name: '--max-difficulty', minimum: 0, maximum: 100, defaultValue: 60 });
+    if (maxDifficulty._tag === 'Err')
+        return maxDifficulty;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 20 });
+    if (limit._tag === 'Err')
+        return limit;
+    const locationCode = parseInteger(args.locationCode, { name: '--location-code', minimum: 1, defaultValue: 2840 });
+    if (locationCode._tag === 'Err')
+        return locationCode;
+    if (maxVolume.value < minVolume.value)
+        return fail(EXIT_CODE.invalidInput, '--max-volume must be at least --min-volume.');
+    if (maxDifficulty.value < minDifficulty.value)
+        return fail(EXIT_CODE.invalidInput, '--max-difficulty must be at least --min-difficulty.');
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Researching keyword ideas', () => resolved.value.api.client.research.keywords({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            topic: args.topic,
+            minVolume: minVolume.value,
+            maxVolume: maxVolume.value,
+            minDifficulty: minDifficulty.value,
+            maxDifficulty: maxDifficulty.value,
+            intent: args.intent,
+            includeRelated: args.related ?? true,
+            verbose: args.verbose ?? false,
+            limit: limit.value,
+            locationCode: locationCode.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderKeywordResearch(value.data));
+}
+async function researchSerp(runtime, globals, args) {
+    const depth = parseInteger(args.depth, { name: '--depth', minimum: 1, maximum: 20, defaultValue: 10 });
+    if (depth._tag === 'Err')
+        return depth;
+    const locationCode = parseInteger(args.locationCode, { name: '--location-code', minimum: 1, defaultValue: 2840 });
+    if (locationCode._tag === 'Err')
+        return locationCode;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Analyzing the SERP', () => resolved.value.api.client.research.serp({
+        params: { siteId: resolved.value.siteId },
+        query: { keyword: args.keyword, depth: depth.value, locationCode: locationCode.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderSerpResearch(value.data));
+}
+async function researchRankings(runtime, globals, args) {
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 50 });
+    if (limit._tag === 'Err')
+        return limit;
+    const minPosition = parseInteger(args.minPosition, { name: '--min-position', minimum: 1, maximum: 100, defaultValue: 1 });
+    if (minPosition._tag === 'Err')
+        return minPosition;
+    const maxPosition = parseInteger(args.maxPosition, { name: '--max-position', minimum: 1, maximum: 100, defaultValue: 20 });
+    if (maxPosition._tag === 'Err')
+        return maxPosition;
+    const locationCode = parseInteger(args.locationCode, { name: '--location-code', minimum: 1, defaultValue: 2840 });
+    if (locationCode._tag === 'Err')
+        return locationCode;
+    const order = parseChoice(args.order, { name: '--order', choices: ['position', 'traffic'], defaultValue: 'position' });
+    if (order._tag === 'Err')
+        return order;
+    if (maxPosition.value < minPosition.value)
+        return fail(EXIT_CODE.invalidInput, '--max-position must be at least --min-position.');
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Researching domain rankings', () => resolved.value.api.client.research.rankings({
+        params: { siteId: resolved.value.siteId },
+        query: {
+            domain: args.domain,
+            limit: limit.value,
+            minPosition: minPosition.value,
+            maxPosition: maxPosition.value,
+            locationCode: locationCode.value,
+            order: order.value,
+        },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderRankingsResearch(value.data));
+}
+async function auditContentDecay(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading content decay', () => resolved.value.api.client.audit.contentDecay({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderContentDecay(value.data));
+}
+async function auditDuplicateClusters(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading duplicate clusters', () => resolved.value.api.client.audit.duplicateClusters({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderDuplicateClusters(value.data));
+}
+async function auditLinkOpportunities(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading link opportunities', () => resolved.value.api.client.audit.linkOpportunities({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderLinkOpportunities(value.data));
+}
+async function contentBriefList(runtime, globals, args) {
+    const status = args.status === undefined
+        ? ok(undefined)
+        : parseChoice(args.status, {
+            name: '--status',
+            choices: ['queued', 'researching', 'ready', 'written', 'published', 'stale', 'failed', 'archived'],
+        });
+    if (status._tag === 'Err')
+        return status;
+    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 25 });
+    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 Content Briefs', () => resolved.value.api.client.content.listBriefs({
+        params: { siteId: resolved.value.siteId },
+        query: { status: status.value, limit: limit.value, offset: offset.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderContentBriefs(value.data));
+}
+async function contentBriefShow(runtime, globals, briefId) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Content Brief', () => resolved.value.api.client.content.showBrief({
+        params: { siteId: resolved.value.siteId, briefId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderContentBrief(value.data));
+}
+async function contentBriefCreate(runtime, globals, args) {
+    const targetPage = args.targetPage === undefined ? ok(undefined) : parseAbsolutePageUrl(args.targetPage);
+    if (targetPage._tag === 'Err')
+        return targetPage;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const confirmed = await confirmMutation(runtime, globals, `Create a Content Brief for ${args.keyword}?`);
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Mutation cancelled.');
+        return ok(undefined);
+    }
+    const response = await withSpinner(runtime, 'Creating Content Brief', () => resolved.value.api.client.content.createBrief({
+        params: { siteId: resolved.value.siteId },
+        body: { keyword: args.keyword, targetPage: targetPage.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderContentBriefCreated(value.data));
+}
 async function backlinksRecoverable(runtime, globals, limitInput, offsetInput) {
     const limit = parseInteger(limitInput, { name: '--limit', minimum: 1, maximum: 200, defaultValue: 100 });
     if (limit._tag === 'Err')
@@ -551,13 +772,162 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
+    const research = defineCommand({
+        meta: { name: 'research', description: 'Read stored and live search research' },
+        subCommands: {
+            overview: defineCommand({
+                meta: { name: 'overview', description: 'Read stored Site metrics and competitor research' },
+                run: ({ args }) => capture(execution, () => researchOverview(runtime, globals), args._, 0)(),
+            }),
+            keywords: defineCommand({
+                meta: { name: 'keywords', description: 'Find live keyword ideas with volume and difficulty' },
+                args: {
+                    'topic': positional('topic', 'Keyword or topic'),
+                    'min-volume': { type: 'string', description: 'Minimum monthly volume' },
+                    'max-volume': { type: 'string', description: 'Maximum monthly volume' },
+                    'min-difficulty': { type: 'string', description: 'Minimum difficulty, 0 to 100' },
+                    'max-difficulty': { type: 'string', description: 'Maximum difficulty, 0 to 100' },
+                    'limit': { type: 'string', description: 'Maximum keywords, 1 to 100' },
+                    'location-code': { type: 'string', description: 'DataForSEO location code' },
+                    'intent': { type: 'string', description: 'Search intent filter' },
+                    'related': { type: 'boolean', default: true, description: 'Include related keywords; use --no-related to exclude them' },
+                    'verbose': { type: 'boolean', description: 'Include full keyword evidence' },
+                },
+                run: ({ args }) => capture(execution, () => researchKeywordIdeas(runtime, globals, {
+                    topic: args.topic,
+                    minVolume: args['min-volume'],
+                    maxVolume: args['max-volume'],
+                    minDifficulty: args['min-difficulty'],
+                    maxDifficulty: args['max-difficulty'],
+                    limit: args.limit,
+                    locationCode: args['location-code'],
+                    intent: args.intent,
+                    related: args.related,
+                    verbose: args.verbose,
+                }), args._, 1)(),
+            }),
+            serp: defineCommand({
+                meta: { name: 'serp', description: 'Analyze one live Google SERP' },
+                args: {
+                    'keyword': positional('keyword', 'Keyword'),
+                    'depth': { type: 'string', description: 'Organic result depth, 1 to 20' },
+                    'location-code': { type: 'string', description: 'DataForSEO location code' },
+                },
+                run: ({ args }) => capture(execution, () => researchSerp(runtime, globals, {
+                    keyword: args.keyword,
+                    depth: args.depth,
+                    locationCode: args['location-code'],
+                }), args._, 1)(),
+            }),
+            rankings: defineCommand({
+                meta: { name: 'rankings', description: 'Research live keyword rankings for a domain' },
+                args: {
+                    'domain': positional('domain', 'Domain without a protocol'),
+                    'limit': { type: 'string', description: 'Maximum keywords, 1 to 100' },
+                    'min-position': { type: 'string', description: 'Minimum position, 1 to 100' },
+                    'max-position': { type: 'string', description: 'Maximum position, 1 to 100' },
+                    'location-code': { type: 'string', description: 'DataForSEO location code' },
+                    'order': { type: 'enum', options: ['position', 'traffic'], description: 'Sort rankings' },
+                },
+                run: ({ args }) => capture(execution, () => researchRankings(runtime, globals, {
+                    domain: args.domain,
+                    limit: args.limit,
+                    minPosition: args['min-position'],
+                    maxPosition: args['max-position'],
+                    locationCode: args['location-code'],
+                    order: args.order,
+                }), args._, 1)(),
+            }),
+        },
+    });
+    const audit = defineCommand({
+        meta: { name: 'audit', description: 'Read stored Site audit reports' },
+        subCommands: {
+            'content-decay': defineCommand({
+                meta: { name: 'content-decay', description: 'List Pages losing Search Console clicks' },
+                run: ({ args }) => capture(execution, () => auditContentDecay(runtime, globals), args._, 0)(),
+            }),
+            'duplicates': defineCommand({
+                meta: { name: 'duplicates', description: 'List duplicate Page clusters' },
+                run: ({ args }) => capture(execution, () => auditDuplicateClusters(runtime, globals), args._, 0)(),
+            }),
+            'link-opportunities': defineCommand({
+                meta: { name: 'link-opportunities', description: 'List internal link opportunities' },
+                run: ({ args }) => capture(execution, () => auditLinkOpportunities(runtime, globals), args._, 0)(),
+            }),
+        },
+    });
+    const content = defineCommand({
+        meta: { name: 'content', description: 'Read and create Content Briefs' },
+        subCommands: {
+            briefs: defineCommand({
+                meta: { name: 'briefs', description: 'Manage Content Briefs' },
+                subCommands: {
+                    list: defineCommand({
+                        meta: { name: 'list', description: 'List Content Briefs' },
+                        args: {
+                            status: {
+                                type: 'enum',
+                                options: ['queued', 'researching', 'ready', 'written', 'published', 'stale', 'failed', 'archived'],
+                                description: 'Filter by status',
+                            },
+                            limit: { type: 'string', description: 'Maximum Content Briefs, 1 to 100' },
+                            offset: { type: 'string', description: 'Pagination offset' },
+                        },
+                        run: ({ args }) => capture(execution, () => contentBriefList(runtime, globals, {
+                            status: args.status,
+                            limit: args.limit,
+                            offset: args.offset,
+                        }), args._, 0)(),
+                    }),
+                    show: defineCommand({
+                        meta: { name: 'show', description: 'Show one Content Brief' },
+                        args: { briefId: positional('brief-id', 'Content Brief ID') },
+                        run: ({ args }) => capture(execution, () => contentBriefShow(runtime, globals, args.briefId), args._, 1)(),
+                    }),
+                    create: defineCommand({
+                        meta: { name: 'create', description: 'Create a Content Brief' },
+                        args: {
+                            'keyword': positional('keyword', 'Target keyword'),
+                            'target-page': { type: 'string', description: 'Absolute target Page URL' },
+                        },
+                        run: ({ args }) => capture(execution, () => contentBriefCreate(runtime, globals, {
+                            keyword: args.keyword,
+                            targetPage: args['target-page'],
+                        }), args._, 1)(),
+                    }),
+                },
+            }),
+        },
+    });
     const search = defineCommand({
         meta: { name: 'search', description: 'Read Search Console state' },
         subCommands: {
             status: defineCommand({
-                meta: { name: 'status', description: 'Read Search Console status' },
+                meta: { name: 'status', description: 'Read the stored Search Console connection' },
                 run: ({ args }) => capture(execution, () => searchStatus(runtime, globals), args._, 0)(),
             }),
+            analytics: defineCommand({
+                meta: { name: 'analytics', description: 'List Search Console query or Page rows' },
+                args: {
+                    'view': positional('pages-or-keywords', 'pages or keywords'),
+                    'period': { type: 'enum', options: ['7d', '28d', '3m', '6m', '12m'], description: 'Search Console period' },
+                    'limit': { type: 'string', description: 'Maximum rows, 1 to 100' },
+                    'page': { type: 'string', description: 'Result page number' },
+                    'search': { type: 'string', description: 'Filter rows by text' },
+                    'sort': { type: 'enum', options: ['clicks', 'impressions', 'ctr', 'position'], description: 'Sort field' },
+                    'sort-dir': { type: 'enum', options: ['asc', 'desc'], description: 'Sort direction' },
+                },
+                run: ({ args }) => capture(execution, () => searchAnalytics(runtime, globals, {
+                    view: args.view,
+                    period: args.period,
+                    limit: args.limit,
+                    page: args.page,
+                    search: args.search,
+                    sort: args.sort,
+                    sortDir: args['sort-dir'],
+                }), args._, 1)(),
+            }),
         },
     });
     return defineCommand({
@@ -613,13 +983,16 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => usage(runtime, globals, args.group), args._, 0)(),
             }),
             actions,
+            audit,
             backlinks,
+            content,
             mentions,
             page,
             performance: defineCommand({
                 meta: { name: 'performance', description: 'Read the stored Site performance overview' },
                 run: ({ args }) => capture(execution, () => performance(runtime, globals), args._, 0)(),
             }),
+            research,
             search,
         },
     });

package/dist/failures.js

@@ -89,9 +89,14 @@ export function fromSdkFailure(error) {
                     message: [
                         `${error.code}: ${error.message}`,
                         ...metadataLines(error),
-                        error.code === 'unauthorized' || error.code === 'auth_expired'
+                        // `unauthorized` is the caller's own credential. `auth_expired` is the
+                        // Site's Search Console connection, which no token change repairs.
+                        error.code === 'unauthorized'
                             ? 'Replace NUXTSEO_TOKEN, or run `nuxtseo login` when using a stored credential.'
                             : undefined,
+                        error.code === 'auth_expired'
+                            ? 'Open site settings in the dashboard, then Search Console, to reconnect.'
+                            : undefined,
                     ].filter((line) => line !== undefined).join('\n'),
                     protocolResponse: error.response,
                 },

package/dist/parse.d.ts

@@ -21,3 +21,8 @@ export declare function parseInteger(input: string | undefined, options: {
     maximum?: number;
     defaultValue: number;
 }): CliResult<number>;
+export declare function parseChoice<const TChoice extends string>(input: string | undefined, options: {
+    name: string;
+    choices: readonly TChoice[];
+    defaultValue?: TChoice;
+}): CliResult<TChoice>;

package/dist/parse.js

@@ -124,3 +124,10 @@ export function parseInteger(input, options) {
     }
     return ok(parsed);
 }
+export function parseChoice(input, options) {
+    if (input === undefined && options.defaultValue !== undefined)
+        return ok(options.defaultValue);
+    if (input !== undefined && options.choices.includes(input))
+        return ok(input);
+    return fail(EXIT_CODE.invalidInput, `${options.name} must be one of: ${options.choices.join(', ')}.`);
+}

package/dist/render.d.ts

@@ -1,9 +1,12 @@
 import type { AccountUsageResponse, SitesListResponse } from '@nuxtseo/protocol/v1';
 import type { ActionList, ActionResolve, ActionShow } from '@nuxtseo/protocol/v1/actions';
+import type { AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities } from '@nuxtseo/protocol/v1/audit';
 import type { Mentions, RecoverableBacklinks } from '@nuxtseo/protocol/v1/backlinks';
-import type { SearchStatusData } from '@nuxtseo/protocol/v1/gsc';
+import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
+import type { 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';
 export declare function renderSites(response: SitesListResponse, selectedSiteId?: string): string;
 export declare function renderUsage(response: AccountUsageResponse): string;
 export declare function renderActions(data: ActionList): string;
@@ -13,5 +16,16 @@ export declare function renderPageInspection(data: PageInspect): string;
 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 renderResearchOverview(data: StoredResearchOverview): string;
+export declare function renderKeywordResearch(data: KeywordResearchData): string;
+export declare function renderSerpResearch(data: SerpResearchData): string;
+export declare function renderRankingsResearch(data: RankingsResearchData): string;
+export declare function renderContentBriefs(data: ContentBriefListData): string;
+export declare function renderContentBrief(data: ContentBrief): string;
+export declare function renderContentBriefCreated(data: ContentBriefCreateData): string;
+export declare function renderContentDecay(data: AuditContentDecay): string;
+export declare function renderDuplicateClusters(data: AuditDuplicateClusters): string;
+export declare function renderLinkOpportunities(data: AuditLinkOpportunities): string;
 export declare function renderRecoverableBacklinks(data: RecoverableBacklinks): string;
 export declare function renderMentions(data: Mentions): string;

package/dist/render.js

@@ -107,16 +107,130 @@ export function renderPerformance(data) {
     ]);
 }
 export function renderSearchStatus(data) {
+    if (data._tag === 'Connected')
+        return fields([['Site', data.site], ['Search Console', 'connected']]);
+    if (data._tag === 'ActionRequired') {
+        const next = data.reason === 'credential_inactive'
+            ? 'Reconnect Search Console in Site settings.'
+            : 'Connect Search Console in Site settings.';
+        return `${fields([['Site', data.site], ['Search Console', 'action required']])}\n${next}`;
+    }
+    return `${fields([['Site', data.site], ['Search Console', 'disconnected']])}\nConnect Search Console in Site settings.`;
+}
+export function renderSearchAnalytics(data) {
+    if (data.type === 'pages') {
+        if (data.rows.length === 0)
+            return 'No Search Console Page rows match these filters.';
+        return [
+            `Search Console Pages (${data.rows.length} of ${data.total})`,
+            ...data.rows.map(row => `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos.toFixed(1)}\n  ${row.url}`),
+        ].join('\n');
+    }
+    if (data.type === 'keywords') {
+        if (data.rows.length === 0)
+            return 'No Search Console query rows match these filters.';
+        return [
+            `Search Console queries (${data.rows.length} of ${data.total})`,
+            ...data.rows.map(row => `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos.toFixed(1)}\n  ${row.keyword}`),
+        ].join('\n');
+    }
+    return fields([
+        ['View', data.type],
+        ['Period', data.period],
+        ['Rows', 'rows' in data ? data.rows.length : data.type === 'timeseries' ? data.daily.length : 0],
+    ]);
+}
+export function renderResearchOverview(data) {
+    const subject = data.subject
+        ? fields([
+            ['Domain', data.subject.domain],
+            ['Organic traffic', data.subject.metrics.organicTraffic],
+            ['Keywords', data.subject.metrics.totalKeywords],
+            ['Traffic value', data.subject.metrics.trafficValue],
+        ])
+        : 'No stored Site research.';
+    const competitors = data.competitors.length === 0
+        ? 'No stored competitors.'
+        : data.competitors.map(row => `${row.domain}  ${row.metrics.organicTraffic ?? 'unknown'} traffic  ${row.quickWins.length} quick wins`).join('\n');
+    return [subject, `Competitors: ${data.summary.competitorCount}`, competitors].join('\n');
+}
+export function renderKeywordResearch(data) {
+    if (data.keywords.length === 0)
+        return data.message ?? `No keyword ideas found for ${data.topic}.`;
+    return [
+        `Keyword ideas for ${data.topic} (${data.keywords.length} of ${data.totalFound})${data.evidence._tag === 'cache' ? '  cached' : ''}`,
+        ...data.keywords.map(row => `${row.volume ?? 'unknown'} volume  ${row.difficulty ?? 'unknown'} difficulty  ${row.intent ?? 'unknown intent'}\n  ${row.keyword}`),
+        ...(data.tip ? [`Tip: ${data.tip}`] : []),
+    ].join('\n');
+}
+export function renderSerpResearch(data) {
+    if (data.results.length === 0)
+        return `No organic SERP results found for ${data.keyword}.`;
+    return [
+        `SERP for ${data.keyword}  ${data.fetchedAt}${data.cached ? '  cached' : ''}`,
+        data.serpFeatures.length ? `Features: ${data.serpFeatures.join(', ')}` : 'Features: none',
+        ...data.results.map(row => `${row.position}. ${row.title}\n  ${row.domain}\n  ${row.url}`),
+    ].join('\n');
+}
+export function renderRankingsResearch(data) {
+    if (data.keywords.length === 0)
+        return data.message ?? `No rankings found for ${data.domain}.`;
+    return [
+        `${data.domain} rankings (${data.keywords.length} of ${data.totalFound})${data.cached ? '  cached' : ''}`,
+        ...data.keywords.map(row => `${row.position}. ${row.keyword}  ${row.volume} volume  ${row.traffic} traffic\n  ${row.url}`),
+    ].join('\n');
+}
+export function renderContentBriefs(data) {
+    if (data.briefs.length === 0)
+        return 'No Content Briefs match these filters.';
+    return [
+        `Content Briefs (${data.briefs.length} of ${data.page.total})`,
+        ...data.briefs.map(brief => `${brief.id}  ${brief.status}\n  ${brief.keyword}`),
+    ].join('\n');
+}
+export function renderContentBrief(data) {
     return fields([
-        ['Site', data.site],
-        ['Connected', data.connected],
-        ['Sync status', data.syncStatus],
-        ['Progress', `${data.progress.percent}%`],
-        ['Last sync', data.lastSyncAt],
-        ['Data available', data.hasData],
-        ['Coverage', `${data.daysSynced}/${data.daysAvailable} days`],
+        ['Content Brief', data.id],
+        ['Keyword', data.keyword],
+        ['Status', data.status],
+        ['Generated', data.generatedAt],
+        ['Updated', data.updatedAt],
+        ['Error', data.error],
     ]);
 }
+export function renderContentBriefCreated(data) {
+    return `${data.created ? 'Created' : 'Found existing'} Content Brief.\n${renderContentBrief(data.brief)}`;
+}
+export function renderContentDecay(data) {
+    if (!data.connected)
+        return 'Connect Search Console to find content decay.';
+    if (data.rows.length === 0)
+        return 'No decaying Pages found.';
+    return [
+        `Content decay (${data.rows.length} of ${data.total})  ${data.clicksLost} clicks lost`,
+        ...data.rows.map(row => `${row.clicksDelta} clicks  ${row.clicksChangePct.toFixed(1)}%\n  ${row.url}`),
+    ].join('\n');
+}
+export function renderDuplicateClusters(data) {
+    if (data.clusters.length === 0)
+        return 'No duplicate clusters found.';
+    return [
+        `Duplicate clusters (${data.clusters.length} of ${data.total})  ${data.pagesAffected} Pages`,
+        ...data.clusters.map(cluster => `${cluster.size} Pages  ${cluster.pathPattern}\n  Keep: ${cluster.keepPath ?? 'not selected'}`),
+    ].join('\n');
+}
+export function renderLinkOpportunities(data) {
+    if (!data.connected)
+        return 'Connect Search Console to find link opportunities.';
+    if (data.textUnavailable)
+        return 'Page text is unavailable. Run a Site scan first.';
+    if (data.rows.length === 0)
+        return 'No link opportunities found.';
+    return [
+        `Link opportunities (${data.rows.length} of ${data.total})`,
+        ...data.rows.map(row => `${row.phrase}\n  From: ${row.sourceUrl}\n  To: ${row.targetUrl}`),
+    ].join('\n');
+}
 export function renderRecoverableBacklinks(data) {
     if (data.items.length === 0)
         return 'No recoverable Backlinks. Every stored inbound link resolves.';

package/dist/runtime.d.ts

@@ -10,6 +10,7 @@ export interface CliRuntime {
     interactive: boolean;
     signal: AbortSignal;
     requestSignal: AbortSignal;
+    requestTimeoutMs?: number;
     readStdin: () => Promise<string>;
 }
 export declare function writeOutput(runtime: CliRuntime, text: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -31,7 +31,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@nuxtseo/sdk": "^0.1.0"
+    "@nuxtseo/sdk": "^0.1.1"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
@@ -44,10 +44,10 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@types/node": "^26.2.0",
-    "publint": "^0.3.23",
+    "publint": "^0.3.24",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
-    "@nuxtseo/protocol": "0.1.0",
-    "@nuxtseo/sdk": "0.1.0"
+    "@nuxtseo/sdk": "0.1.1",
+    "@nuxtseo/protocol": "0.1.1"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -1,35 +1,31 @@
 ---
 name: nuxtseo-cli
-description: Drive the `nuxtseo` CLI (@nuxtseo/cli) to read and act on the NuxtSEO Pro data a Site already stores - next actions, page observations, Lighthouse and Core Web Vitals, Search Console sync state, and account usage. Use this whenever the user mentions NuxtSEO, `nuxtseo`, "what should I fix on my site", next actions, page scans, or asks you to check or resolve stored SEO issues, even when they do not name the CLI. Also use it before writing any script or CI step that shells out to `nuxtseo`. The CLI does NOT do research work; keyword ideas, SERP analysis, Search Console query and page data, rank tracking, competitors, and content briefs live in the `nuxt-seo-pro` MCP server instead, and this skill says which tool to reach for.
+description: Drive the `nuxtseo` CLI for Site triage, Search Console rows, keyword and competitor research, SERP analysis, rankings, link opportunities, Content Briefs, content decay, duplicate clusters, scans, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or NuxtSEO automation.
 ---
 
 # NuxtSEO CLI
 
 `nuxtseo` reads a Site through the NuxtSEO public API. Every command goes
-through `@nuxtseo/sdk`. The CLI never calls MCP, private routes, or providers,
-so it has no hidden fallback: what it prints is what the API returned.
+through `@nuxtseo/sdk`. The CLI never calls MCP or private routes. Live
+research reaches providers only through a declared public API operation.
 
 Use it to answer "what is wrong with this site and what did I break", then fix
 the code in the repo you are working in.
 
-## What this CLI does not cover
+## Data boundaries
 
-The CLI reads what the product already stored for a Site. It runs no research.
+Most commands read stored Site evidence. Three commands can start live research:
 
-| The user wants | Reach for |
-| --- | --- |
-| Keyword ideas, volume, difficulty, SERP analysis | MCP `keyword_research`, `domain_info` |
-| Search Console queries, pages, striking distance | MCP `gsc_query` |
-| Rank history for tracked keywords | MCP `rank_tracker` |
-| Competitors, mentions, backlinks, link opportunities | MCP `competitors`, `mentions`, `backlinks`, `link_opportunities` |
-| Content briefs, content decay, duplicate clusters | MCP `content_briefs`, `content_decay`, `duplicate_clusters` |
+- `research keywords`
+- `research serp`
+- `research rankings`
 
-Those tools come from the `nuxt-seo-pro` MCP server, which the user connects
-separately. If the MCP server is not connected and the job is research shaped,
-say so and stop. Do not approximate research output from CLI data.
+These commands use the Team research allowance when the server misses its
+cache. Keyword JSON reports cache use in `evidence`. SERP and ranking JSON
+report `cached`.
 
-`nuxtseo search status` reports only whether Search Console is connected and how
-far the sync got. It returns no query rows.
+`search status` reads stored connection state. It never waits for Google.
+`search analytics` reads Search Console rows through the public API.
 
 ## Get the binary
 
@@ -109,13 +105,26 @@ handling failures, read [CLI protocol](references/protocol.md).
 | `sites list` | Every accessible Site | Source of Site IDs |
 | `sites use <site-id>` | – | Persists a default Site for the human, not for you |
 | `usage` | Plan and meters | `--group integrations\|compute\|capacity` |
-| `actions list` | Server ranked next actions | `--limit 1..25` (default 10), `--offset` |
-| `actions show <action-id>` | One action plus evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
-| `actions resolve <action-id>` | – | Mutation. Claims the action and starts server verification |
+| `actions list` | Server-ranked issues and opportunities | `--limit 1..25` (default 10), `--offset` |
+| `actions show <action-id>` | One issue or opportunity plus evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
+| `actions resolve <action-id>` | – | Mutation. Claims the issue or opportunity and starts server verification |
+| `backlinks recoverable` | Stored recoverable backlinks | `--limit 1..200`, `--offset` |
+| `mentions list` | Stored mentions | `--limit 1..200` |
 | `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved` |
 | `page scan <url>` | – | Mutation. Starts mobile and desktop scans |
 | `performance` | Site performance overview | Medians for perf, a11y, SEO, LCP, TBT, CLS |
-| `search status` | Search Console connection and sync progress | Check this before trusting search data |
+| `search status` | Stored Search Console connection | Provider free |
+| `search analytics <pages\|keywords>` | Search Console Page or query rows | `--period`, `--limit`, `--page`, `--search` |
+| `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 |
+| `research rankings <domain>` | Live domain rankings | Current keywords and domain metrics |
+| `audit link-opportunities` | Stored internal link opportunities | Includes crawl coverage |
+| `audit content-decay` | Stored decaying Pages | Includes Search Console loss evidence |
+| `audit duplicates` | Stored duplicate clusters | Includes members and keep candidate |
+| `content briefs list` | Content Brief summaries | `--status`, `--limit`, `--offset` |
+| `content briefs show <brief-id>` | One Content Brief | Includes its grounded payload |
+| `content briefs create <keyword>` | – | Mutation. `--target-page` is optional |
 | `config` | Local config path, API host, selected Site | Local only |
 
 `page inspect` and `page scan` take an absolute URL, for example
@@ -152,11 +161,7 @@ command exits `5` with `stale_evidence`; re-run step 2 and decide again.
 - Ask before you mutate. `actions resolve` and `page scan` consume quota and
   change server state. `--yes` is consent you are borrowing from the user, so
   get it first unless the user already asked for that exact action.
-- Do not loop over pages or URLs unattended. Each call is a real API request
-  against a metered plan. Check `nuxtseo usage --json` if you plan a batch.
-- Report failures as they are. The CLI has no cache and no fallback path, so a
-  failure means the data is genuinely unavailable, not that another route may
-  work.
-- Do not treat an empty result as a clean bill of health. `search status` may
-  report an unfinished sync, and a Page with no stored observations may simply
-  never have been crawled.
+- Do not loop over Pages, keywords, or domains unattended. Check `usage` first.
+- Live research can consume allowance. A cached result does not consume a unit.
+- Report failures as they are. The CLI has no MCP or private-route fallback.
+- Do not treat an empty result as clean. The Site may have incomplete evidence.