@nuxtseo/cli 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
-# NuxtSEO CLI
+# `nuxtseo` CLI
 
-Use NuxtSEO public Site operations from a terminal, script, or coding agent.
+Use Nuxt SEO public Site operations from a terminal, script, or coding agent.
 The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP or
 private routes. Live research uses declared public API operations.
 
@@ -81,7 +81,7 @@ When keychain support is unavailable, it warns on stderr and uses
 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
+Nuxt SEO dashboard when it must stop working everywhere. An environment token
 always wins and is unchanged by login or logout.
 
 API host resolution order is:
@@ -216,9 +216,6 @@ 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
 ```
@@ -256,7 +253,7 @@ reads retained rows and spends nothing.
 `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.
+`page inspect <url>` reads the Nuxt SEO observation store for the same URL.
 `research keywords`, `research serp`, and `research rankings` can use the Team
 research limit. Keyword responses report cache use in `evidence`. SERP and
 ranking responses report `cached: true`. A cached response spends nothing.
@@ -279,7 +276,6 @@ The CLI fetches one page per invocation by default. It never merges responses.
 | `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

package/dist/ansi.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Removes every ANSI escape sequence from one string.
+ */
+export declare function stripAnsi(value: string): string;
+/**
+ * Serializes a value as JSON with every string value free of ANSI escapes.
+ */
+export declare function stringifyWithoutAnsi(value: unknown): string;

package/dist/ansi.js

@@ -0,0 +1,35 @@
+/**
+ * Terminal styling never belongs in machine output.
+ *
+ * `citty` builds its own argument errors with `cyan(...)`, and it decides once,
+ * at import time, whether to emit colour. The CLI cannot turn that decision off
+ * after the fact, and the same risk exists for any other dependency whose text
+ * reaches a JSON envelope. So the CLI strips escape sequences at the boundary
+ * where machine output is written, which covers every producer at once.
+ */
+/**
+ * A control sequence: `ESC [`, parameter and intermediate bytes, then one final
+ * byte. Colour, cursor moves and erase sequences all take this form.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_CONTROL_SEQUENCE = /\u001B\[[\u0030-\u003F]*[\u0020-\u002F]*[\u0040-\u007E]/g;
+/**
+ * An operating system command, such as a terminal hyperlink or a window title.
+ * It ends with BEL or with `ESC \`.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_OPERATING_SYSTEM_COMMAND = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/g;
+/**
+ * Removes every ANSI escape sequence from one string.
+ */
+export function stripAnsi(value) {
+    return value
+        .replace(ANSI_OPERATING_SYSTEM_COMMAND, '')
+        .replace(ANSI_CONTROL_SEQUENCE, '');
+}
+/**
+ * Serializes a value as JSON with every string value free of ANSI escapes.
+ */
+export function stringifyWithoutAnsi(value) {
+    return JSON.stringify(value, (_key, entry) => typeof entry === 'string' ? stripAnsi(entry) : entry);
+}

package/dist/cli.js

@@ -1,5 +1,6 @@
 import * as prompts from '@clack/prompts';
 import { renderUsage, runCommand } from 'citty';
+import { stripAnsi } from './ansi.js';
 import { fromStateError, loadApiContext } from './api.js';
 import { commandWithGlobalOptions, describeCommand, resolveCommand, validateCommandOptions, } from './command-contract.js';
 import { createRootCommand } from './commands.js';
@@ -15,6 +16,9 @@ function writeUpdateNotice(runtime, notice) {
 }
 function report(runtime, failure, json = false, notice = null) {
     if (json) {
+        // `--json` means a program reads both streams. Terminal styling is noise
+        // there, so stderr is stripped as well as stdout.
+        failure = { ...failure, message: stripAnsi(failure.message) };
         if (failure.protocolResponse !== undefined) {
             writeProtocolResponse(runtime, failure.protocolResponse);
         }
@@ -198,7 +202,7 @@ async function interactiveBare(runtime, globals) {
         return fromStateError(apiUrl.error);
     if (config._tag === 'Err')
         return fromStateError(config.error);
-    prompts.intro(`NuxtSEO ${VERSION}`, { input: runtime.input, output: runtime.error });
+    prompts.intro(`nuxtseo ${VERSION}`, { input: runtime.input, output: runtime.error });
     prompts.note([
         `Authentication: ${auth.value.authenticated ? auth.value.source : 'not configured'}`,
         `API: ${apiUrl.value.apiUrl}`,
@@ -211,7 +215,7 @@ async function interactiveBare(runtime, globals) {
             { 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: 'content', label: 'Plan content', hint: 'Decay, duplicates, and annotations' },
             { value: 'account', label: 'Account and setup', hint: config.value.siteId ?? 'no Site selected' },
             { value: 'exit', label: 'Exit' },
         ],
@@ -352,8 +356,6 @@ async function interactiveBare(runtime, globals) {
         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' },
                 { value: 'annotations', label: 'Chart annotations', hint: 'mark what you shipped' },
@@ -364,22 +366,11 @@ async function interactiveBare(runtime, globals) {
         });
         if (typeof task === 'symbol')
             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);
-        if (task === 'annotations')
-            return runInteractiveCommand(['annotations', 'list'], 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);
+        return runInteractiveCommand(['annotations', 'list'], runtime, globals);
     }
     const task = await prompts.select({
         message: 'Account and setup',
@@ -405,7 +396,7 @@ export async function runCli(rawArgs, runtime) {
     // Started before parsing so the registry round trip overlaps the command. The
     // check reads a local cache and never rejects; a slow registry only delays
     // this line, never the command result itself.
-    const updateCheck = checkForUpdate({ paths: runtime.paths, env: runtime.env });
+    const updateCheck = checkForUpdate({ paths: runtime.paths, env: runtime.env, onDiagnostic: line => writeDiagnostic(runtime, line) });
     const parsed = extractGlobalOptions(rawArgs);
     if (parsed._tag === 'Err') {
         const notice = await updateCheck;
@@ -416,10 +407,15 @@ export async function runCli(rawArgs, runtime) {
     const effectiveRuntime = {
         ...runtime,
         interactive: runtime.interactive && !globals.json && !globals.noInput,
-        requestSignal: AbortSignal.any([
-            runtime.requestSignal,
-            AbortSignal.timeout(globals.timeoutMs),
-        ]),
+        // A getter, so each request reads a fresh `--timeout-ms` deadline. One timer
+        // made here covered the whole process: an `--all` walk of healthy pages
+        // exited 6 once their SUM passed the per-request limit.
+        get requestSignal() {
+            return AbortSignal.any([
+                runtime.requestSignal,
+                AbortSignal.timeout(globals.timeoutMs),
+            ]);
+        },
         requestTimeoutMs: globals.timeoutMs,
     };
     if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {

package/dist/commands.d.ts

@@ -24,4 +24,11 @@ export type NextPage = {
 } | {
     _tag: 'Done';
 };
+/**
+ * The seed rule is known before the request runs. The provider answers a
+ * refused seed with 200, an empty list, and a `message`, which reads as "no
+ * demand for this topic". So the CLI checks the rule first and exits 2 without
+ * spending a research request.
+ */
+export declare function parseResearchTopic(topic: string): CliResult<string>;
 export declare function createRootCommand(runtime: CliRuntime, globals: GlobalOptions, execution: CommandExecution): CommandDef<any>;

package/dist/commands.js

@@ -8,17 +8,37 @@ 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, parsePageUrlOrPath, parseRatio } from './parse.js';
-import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentBrief, renderContentBriefCreated, renderContentBriefs, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUsage, } from './render.js';
+import { PULL_PERIODS, runPull } from './pull.js';
+import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { installSkill, SKILL_AGENTS } from './skill.js';
 import { clearCredential, getCredentialStatus, readConfig, resolveApiUrl, saveCredential, updateConfig, } from './state/index.js';
 import { VERSION } from './version.js';
+/**
+ * Some read operations answer 200 with an empty list and a `message` that says
+ * why it is empty. A refused argument and a genuinely empty result look the
+ * same in the envelope, so a caller that reads only the list draws the wrong
+ * conclusion. Text output already prints the note. Machine output must not
+ * change the envelope, so the note goes to stderr, where it cannot be lost.
+ */
+function reportDataNote(runtime, value) {
+    const data = typeof value === 'object' && value !== null ? value.data : undefined;
+    if (typeof data !== 'object' || data === null)
+        return;
+    const { message, tip } = data;
+    const lines = [message, tip].filter((line) => typeof line === 'string' && line.trim().length > 0);
+    if (lines.length > 0)
+        writeDiagnostic(runtime, `Note: ${lines.join(' ')}`);
+}
 function emit(runtime, globals, value, render) {
-    if (globals.json)
+    if (globals.json) {
         writeProtocolResponse(runtime, value);
-    else
+        reportDataNote(runtime, value);
+    }
+    else {
         writeOutput(runtime, render(value));
+    }
 }
 function present(runtime, globals, result, render) {
     if (result._tag === 'Err')
@@ -211,7 +231,7 @@ async function logout(runtime, globals) {
     else {
         writeOutput(runtime, cleared.value.removed ? 'Local credential removed.' : 'No stored credential.');
     }
-    writeDiagnostic(runtime, 'Token revocation remains in the NuxtSEO dashboard. NUXTSEO_TOKEN, when set, is unchanged.');
+    writeDiagnostic(runtime, 'Token revocation remains in the Nuxt SEO dashboard. NUXTSEO_TOKEN, when set, is unchanged.');
     return ok(undefined);
 }
 async function whoami(runtime, globals) {
@@ -350,7 +370,7 @@ async function feedbackSubmit(runtime, globals, args) {
     const body = accountFeedbackBodySchema.safeParse({ ...args, cliVersion: VERSION });
     if (!body.success)
         return fail(EXIT_CODE.invalidInput, 'Pass valid --command, --comment, and --agent values. Read feedback submit --help for limits.', undefined, 'invalid_cli_input');
-    const confirmed = await confirmMutation(runtime, globals, 'Submit this agent report to NuxtSEO feedback?');
+    const confirmed = await confirmMutation(runtime, globals, 'Submit this agent report to Nuxt SEO feedback?');
     if (confirmed._tag === 'Err')
         return confirmed;
     if (!confirmed.value) {
@@ -718,7 +738,37 @@ async function researchOverview(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderResearchOverview(value.data));
 }
+/**
+ * DataForSEO refuses these characters, so the research provider removes them
+ * before it counts the words of a seed. Mirrored from
+ * `modules/dataforseo/src/runtime/server/utils/seo-tools/keyword-research.ts`.
+ */
+const RESEARCH_FORBIDDEN_CHARS = /[`!@%^()={};<>?\\|#/~\u2015\u{1F000}-\u{1FFFF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}]/gu;
+/** The provider accepts 1 to 3 words per seed keyword. */
+const RESEARCH_SEED_MAX_WORDS = 3;
+function sanitizeResearchSeed(seed) {
+    return seed.replace(RESEARCH_FORBIDDEN_CHARS, '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * The seed rule is known before the request runs. The provider answers a
+ * refused seed with 200, an empty list, and a `message`, which reads as "no
+ * demand for this topic". So the CLI checks the rule first and exits 2 without
+ * spending a research request.
+ */
+export function parseResearchTopic(topic) {
+    const seeds = topic.split(',').map(sanitizeResearchSeed).filter(seed => seed.length >= 2);
+    if (seeds.length === 0)
+        return fail(EXIT_CODE.invalidInput, 'topic must hold letters or digits. Characters like @ # / % ! are removed.');
+    const tooLong = seeds.find(seed => seed.split(' ').length > RESEARCH_SEED_MAX_WORDS);
+    if (tooLong !== undefined) {
+        return fail(EXIT_CODE.invalidInput, `topic seed "${tooLong}" holds more than ${RESEARCH_SEED_MAX_WORDS} words. Use 1 to 3 words per seed. Separate seeds with a comma.`);
+    }
+    return ok(topic);
+}
 async function researchKeywordIdeas(runtime, globals, args) {
+    const topic = parseResearchTopic(args.topic);
+    if (topic._tag === 'Err')
+        return topic;
     const minVolume = parseInteger(args.minVolume, { name: '--min-volume', minimum: 0, defaultValue: 10 });
     if (minVolume._tag === 'Err')
         return minVolume;
@@ -747,7 +797,7 @@ async function researchKeywordIdeas(runtime, globals, args) {
     const response = await withSpinner(runtime, 'Researching keyword ideas', () => resolved.value.api.client.research.keywords({
         params: { siteId: resolved.value.siteId },
         query: {
-            topic: args.topic,
+            topic: topic.value,
             minVolume: minVolume.value,
             maxVolume: maxVolume.value,
             minDifficulty: minDifficulty.value,
@@ -954,6 +1004,10 @@ async function analyticsQuery(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderAnalytics(view.value, value.data));
 }
+/** A count with its noun, so output never reads "1 files". */
+function count(total, noun) {
+    return `${total} ${noun}${total === 1 ? '' : 's'}`;
+}
 async function skillInstallCommand(runtime, globals, args) {
     const agent = parseChoice(args.agent, { name: '--agent', choices: SKILL_AGENTS, defaultValue: 'claude' });
     if (agent._tag === 'Err')
@@ -961,7 +1015,7 @@ async function skillInstallCommand(runtime, globals, args) {
     // The state directory is `<home>/.nuxtseo`, so its parent is the home the
     // agent directories sit beside.
     const homeDirectory = dirname(runtime.paths.directory);
-    const installed = await installSkill({ agent: agent.value, homeDirectory, target: args.target });
+    const installed = await installSkill({ agent: agent.value, homeDirectory, target: args.target, paths: runtime.paths });
     if (installed._tag === 'Err')
         return installed;
     if (globals.json) {
@@ -969,12 +1023,20 @@ async function skillInstallCommand(runtime, globals, args) {
             _tag: 'CliSkillInstall',
             schemaVersion: 1,
             agent: installed.value.agent,
+            version: installed.value.version,
             source: installed.value.source,
             destination: installed.value.destination,
+            resolvedDestination: installed.value.resolvedDestination,
+            written: installed.value.written,
+            pruned: installed.value.pruned,
         });
     }
     else {
-        writeOutput(runtime, `Installed the nuxtseo-cli skill for ${installed.value.agent} at ${installed.value.destination}.`);
+        writeOutput(runtime, [
+            `Installed the nuxtseo-cli skill ${installed.value.version} for ${installed.value.agent}.`,
+            `Location: ${installed.value.resolvedDestination}`,
+            `Wrote ${count(installed.value.written, 'file')}. Removed ${count(installed.value.pruned, 'stale file')}.`,
+        ].join('\n'));
     }
     return ok(undefined);
 }
@@ -1026,65 +1088,6 @@ async function timelineEntries(runtime, globals, args) {
     }, { 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)
-        : 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;
-    return collect(runtime, globals, {
-        all: args.all === true,
-        message: 'Loading Content Briefs',
-        start: { offset: offset.value },
-        fetch: position => resolved.value.api.client.content.listBriefs({
-            params: { siteId: resolved.value.siteId },
-            query: { status: status.value, limit: limit.value, offset: position.offset ?? 0 },
-        }, { signal: runtime.requestSignal }),
-        render: value => renderContentBriefs(value.data),
-        next: value => offsetPage(value.data.page),
-    });
-}
-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));
-}
 const VITALS_FORM_FACTORS = ['phone', 'desktop', 'all'];
 const VITALS_METRICS = ['lcp', 'inp', 'cls'];
 const VITALS_FORM_FACTOR_WIRE = {
@@ -1907,51 +1910,6 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
-    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' },
-                            all: { type: 'boolean', description: 'Repeat until every page is written; one envelope per page' },
-                        },
-                        run: ({ args }) => capture(execution, () => contentBriefList(runtime, globals, {
-                            status: args.status,
-                            limit: args.limit,
-                            offset: args.offset,
-                            all: args.all,
-                        }), 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: {
@@ -2108,6 +2066,23 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
+    const pull = defineCommand({
+        meta: { name: 'pull', description: 'Write every stored-evidence read for one Site as NDJSON' },
+        args: {
+            'include': { type: 'string', description: 'Comma separated command names to run instead of the default set' },
+            'exclude': { type: 'string', description: 'Comma separated command names to drop' },
+            'with-research': { type: 'boolean', description: 'Add the reads that can start live research; they draw on the Team allowance' },
+            'period': { type: 'enum', options: [...PULL_PERIODS], description: 'Search Console period for the search analytics reads' },
+            'concurrency': { type: 'string', description: 'Reads in flight at once, 1 to 8' },
+        },
+        run: ({ args }) => capture(execution, () => runPull(runtime, globals, {
+            include: args.include,
+            exclude: args.exclude,
+            withResearch: args['with-research'],
+            period: args.period,
+            concurrency: args.concurrency,
+        }, apiAndSite), args._, 0)(),
+    });
     const timeline = defineCommand({
         meta: { name: 'timeline', description: 'Read the Timeline — what changed on the Site' },
         subCommands: {
@@ -2138,10 +2113,10 @@ export function createRootCommand(runtime, globals, execution) {
         meta: {
             name: 'nuxtseo',
             version: VERSION,
-            description: 'Use NuxtSEO from a terminal or automation',
+            description: 'Use Nuxt SEO from a terminal or automation',
         },
         args: {
-            'api-url': { type: 'string', description: 'Override the NuxtSEO API host' },
+            'api-url': { type: 'string', description: 'Override the Nuxt SEO API host' },
             'site': { type: 'string', description: 'Override the selected Site' },
             'json': { type: 'boolean', description: 'Write machine JSON; protocol envelopes remain unchanged' },
             'no-input': { type: 'boolean', description: 'Disable every interactive prompt' },
@@ -2176,7 +2151,7 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             sites,
             feedback: defineCommand({
-                meta: { name: 'feedback', description: 'Report CLI problems to NuxtSEO' },
+                meta: { name: 'feedback', description: 'Report CLI problems to Nuxt SEO' },
                 subCommands: {
                     submit: defineCommand({
                         meta: { name: 'submit', description: 'Submit sanitized agent feedback without selecting a Site' },
@@ -2211,7 +2186,6 @@ export function createRootCommand(runtime, globals, execution) {
             actions,
             audit,
             backlinks,
-            content,
             mentions,
             page,
             performance: defineCommand({
@@ -2219,6 +2193,7 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => performance(runtime, globals), args._, 0)(),
             }),
             annotations,
+            pull,
             research,
             scans,
             search,

package/dist/failures.d.ts

@@ -12,7 +12,7 @@ export declare const EXIT_CODE: {
     readonly interrupted: 130;
 };
 export type ExitCode = typeof EXIT_CODE[keyof typeof EXIT_CODE];
-export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
+export type LocalFailureCode = 'authentication_required' | 'authorization_required' | 'confirmation_required' | 'conflict' | 'contract_violation' | 'infrastructure_failure' | 'interrupted' | 'invalid_cli_input' | 'not_found' | 'paging_cap_reached' | 'pull_incomplete' | 'request_timeout' | 'retryable_failure' | 'site_ambiguous' | 'site_empty' | 'site_not_accessible' | 'state_error' | 'token_input_required' | 'transport_failure' | 'unexpected';
 export type CliFailureCode = LocalFailureCode | Extract<SdkFailure, {
     _tag: 'ApiFailure';
 }>['code'];
@@ -24,14 +24,54 @@ export interface CliFailure {
     cause?: unknown;
     protocolResponse?: unknown;
 }
+export interface CliErr {
+    _tag: 'Err';
+    error: CliFailure;
+}
 export type CliResult<T> = {
     _tag: 'Ok';
     value: T;
+} | CliErr;
+export declare function ok<T>(value: T): CliResult<T>;
+export declare function fail(exitCode: ExitCode, message: string, cause?: unknown, code?: CliFailureCode): CliErr;
+/**
+ * Which side of a `contract_violation` runs the older contract.
+ *
+ * The CLI knows the contract version it was built against. The API reports its
+ * own in the `X-NuxtSEO-Version` response header, which the SDK keeps on
+ * `metadata.version`. When the two differ, the direction of the skew is a fact.
+ * When they match, or the header is absent, the CLI cannot observe a direction,
+ * so the message must not name one.
+ *
+ * Bug 2026-09-21: a field landed in a client response schema before the API
+ * deployed it. A newer CLI rejected an older API response, and the old message
+ * told the operator to update the CLI, which was already the newest part.
+ */
+export type ContractSkew = {
+    _tag: 'CliContractOlder';
+    cliContract: string;
+    apiContract: string;
 } | {
-    _tag: 'Err';
-    error: CliFailure;
+    _tag: 'ApiContractOlder';
+    cliContract: string;
+    apiContract: string;
+} | {
+    _tag: 'ContractVersionsMatch';
+    contract: string;
+} | {
+    _tag: 'ApiContractUnknown';
+    cliContract: string;
 };
-export declare function ok<T>(value: T): CliResult<T>;
-export declare function fail(exitCode: ExitCode, message: string, cause?: unknown, code?: CliFailureCode): CliResult<never>;
-export declare function fromSdkFailure(error: SdkFailure): CliResult<never>;
+/**
+ * Classify the skew from what the response actually carried.
+ *
+ * `apiContract` is the value of the `X-NuxtSEO-Version` response header, or
+ * `undefined` when the API sent no header the SDK could read.
+ */
+export declare function classifyContractSkew(apiContract: string | undefined, cliContract?: string): ContractSkew;
+/**
+ * The remediation a caller can act on, and nothing the CLI cannot observe.
+ */
+export declare function contractSkewLines(skew: ContractSkew): string[];
+export declare function fromSdkFailure(error: SdkFailure): CliErr;
 export declare function unexpectedFailure(cause: unknown): CliFailure;