@nuxtseo/cli 0.1.0

package/dist/state/result.d.ts

@@ -0,0 +1,67 @@
+export type StateKind = 'auth' | 'config';
+export type StateOperation = 'read' | 'write' | 'delete';
+export interface CorruptConfigError {
+    _tag: 'CorruptConfig';
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export interface CorruptAuthError {
+    _tag: 'CorruptAuth';
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export interface ReadOnlyFilesystemError {
+    _tag: 'ReadOnlyFilesystem';
+    kind: StateKind;
+    operation: Exclude<StateOperation, 'read'>;
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export interface StateFilesystemError {
+    _tag: 'StateFilesystemError';
+    kind: StateKind;
+    operation: StateOperation;
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export interface InvalidApiUrlError {
+    _tag: 'InvalidApiUrl';
+    source: 'argument' | 'environment';
+    message: string;
+}
+export interface InvalidConfigError {
+    _tag: 'InvalidConfig';
+    message: string;
+}
+export interface InvalidCredentialError {
+    _tag: 'InvalidCredential';
+    source: 'input' | 'environment';
+    message: string;
+}
+export interface KeychainUnavailableError {
+    _tag: 'KeychainUnavailable';
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export interface KeychainFailureError {
+    _tag: 'KeychainFailure';
+    operation: 'read' | 'write' | 'delete';
+    path: string;
+    message: string;
+    cause?: unknown;
+}
+export type StateError = CorruptConfigError | CorruptAuthError | ReadOnlyFilesystemError | StateFilesystemError | InvalidApiUrlError | InvalidConfigError | InvalidCredentialError | KeychainUnavailableError | KeychainFailureError;
+export type StateResult<TValue, TError = StateError> = {
+    _tag: 'Ok';
+    value: TValue;
+} | {
+    _tag: 'Err';
+    error: TError;
+};
+export declare function ok<TValue>(value: TValue): StateResult<TValue, never>;
+export declare function err<TError>(error: TError): StateResult<never, TError>;

package/dist/state/result.js

@@ -0,0 +1,6 @@
+export function ok(value) {
+    return { _tag: 'Ok', value };
+}
+export function err(error) {
+    return { _tag: 'Err', error };
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,2 @@
+import manifest from '../package.json' with { type: 'json' };
+export const VERSION = manifest.version;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nuxtseo/cli",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Command line interface for the NuxtSEO public API.",
+  "license": "MIT",
+  "homepage": "https://nuxtseo.com/pro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/nuxtseo.com.git",
+    "directory": "packages/cli"
+  },
+  "sideEffects": [
+    "./dist/cli-entry.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nuxtseo": "./dist/cli-entry.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@nuxtseo/sdk": "^0.1.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "citty": "^0.2.2",
+    "pathe": "^2.0.3"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^26.2.0",
+    "publint": "^0.3.23",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
+    "@nuxtseo/protocol": "0.1.0",
+    "@nuxtseo/sdk": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "check:attw": "attw --pack --profile esm-only",
+    "check:publint": "publint --pack npm",
+    "check:package": "pnpm run build && pnpm run check:publint && pnpm run check:attw"
+  }
+}

package/skills/nuxtseo-cli/SKILL.md

@@ -0,0 +1,162 @@
+---
+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.
+---
+
+# 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.
+
+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
+
+The CLI reads what the product already stored for a Site. It runs no 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` |
+
+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.
+
+`nuxtseo search status` reports only whether Search Console is connected and how
+far the sync got. It returns no query rows.
+
+## Get the binary
+
+```sh
+npx -y @nuxtseo/cli@latest --version    # no install
+pnpm add -g @nuxtseo/cli                # or npm install --global
+```
+
+Node 22 or newer is required. Inside the NuxtSEO monorepo itself, the package is
+not published, so run the built entry directly:
+
+```sh
+node packages/cli/dist/cli-entry.js --version
+```
+
+Exit `127` or `command not found` means the CLI is absent. That is not exit `3`;
+no token has been checked yet. Install it, then continue.
+
+## Before the first command
+
+```sh
+nuxtseo whoami --json          # validates the token, lists Site count
+```
+
+Exit `3` means there is no working token. Ask the user to run `nuxtseo login`
+themselves: it opens a browser, they approve the pairing, and the CLI stores the
+token. Do not run `login` for them; it needs a person at the browser, and in a
+non-interactive shell it falls back to reading a token from stdin instead.
+
+The alternative is a token created at
+<https://nuxtseo.com/pro/dashboard/settings/api-tokens> and exported as
+`NUXTSEO_TOKEN`. Either way the token is bound to a Team role, and that role
+gates what it can do.
+
+Never put a token in a command argument, a file you write, or a commit. `login`
+reads a token from a hidden prompt or stdin only.
+
+Resolve the Site once and reuse it. `nuxtseo sites list --json` prints every
+accessible Site with its ID.
+
+## How to call it as an agent
+
+Always pass `--json` and always pass `--site <site-id>`.
+
+```sh
+nuxtseo actions list --site site_123 --json
+```
+
+`--json` writes the complete protocol envelope to stdout and one newline. It
+also disables prompts. Diagnostics, warnings, spinners, and failure messages go
+to stderr, so stdout stays parseable.
+
+`--site` matters for a second reason: an explicit Site ID goes straight to the
+operation and skips the Sites read, so a token whose role cannot list Sites
+still works. If more than one Site is accessible and `--site` is absent, the CLI
+exits `5` rather than guessing.
+
+Other flags worth knowing:
+
+| Flag | Use it when |
+| --- | --- |
+| `--yes`, `-y` | The command mutates. Without it, a non-interactive run exits `2`. |
+| `--timeout-ms <ms>` | The default 30000 ms deadline is too short. Maximum is 300000. |
+| `--api-url <url>` | Testing against a non-production host. |
+| `--no-input` | Running in a TTY but no prompt is wanted. `--json` already implies this. |
+
+Unknown options exit `2` before any network work, so a typo costs nothing.
+
+Parse JSON. Never scrape human output. Before parsing envelopes, paging, or
+handling failures, read [CLI protocol](references/protocol.md).
+
+## Commands
+
+| Command | Reads | Notes |
+| --- | --- | --- |
+| `whoami` | Token validity, API host, Site count | Cheapest health check |
+| `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 |
+| `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 |
+| `config` | Local config path, API host, selected Site | Local only |
+
+`page inspect` and `page scan` take an absolute URL, for example
+`https://example.com/about`.
+
+`--help --json` returns a `CliHelp` value for one command level: its
+`arguments`, the inherited `globalOptions`, and its `subcommands` as names and
+descriptions only. To learn a subcommand's own flags, ask it directly, for
+example `nuxtseo actions list --help --json`. Use this instead of guessing a
+flag, and prefer the table above for anything it already answers.
+
+## The triage loop
+
+This is the sequence that turns CLI output into a code change:
+
+1. `nuxtseo actions list --site <id> --json` gives ranked work with an ID, a
+   diagnosis, an effort, and an affected page count.
+2. `nuxtseo actions show <action-id> --site <id> --json` gives the evidence:
+   which pages, which finding type, and when it was observed.
+3. Fix the cause in the repository. The evidence names URLs; map them back to
+   routes, components, or config.
+4. Deploy or preview the fix, then `nuxtseo page scan <url> --site <id> --yes
+   --json` to ask for fresh scans of a page you changed.
+5. `nuxtseo actions resolve <action-id> --site <id> --yes --json` claims the
+   action. The server verifies it; the CLI does not mark anything fixed by
+   itself.
+
+Resolve reads the action first and sends the current `artifactVersion` for you.
+Do not construct that field by hand. If the evidence moved under you, the
+command exits `5` with `stale_evidence`; re-run step 2 and decide again.
+
+## Guardrails
+
+- 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.

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

@@ -0,0 +1,64 @@
+# CLI protocol
+
+Read this before parsing output, paging, or handling a nonzero exit.
+
+## Response shape
+
+Success:
+
+```json
+{ "data": { }, "meta": { "requestId": "...", "version": "1.0" } }
+```
+
+Protocol failure, still on stdout, with recovery details on stderr:
+
+```json
+{ "error": { "code": "rate_limited", "message": "...", "requestId": "...", "retryable": true, "details": {} } }
+```
+
+Read `data`. The CLI does not unwrap, rename, rank, or enrich fields.
+
+Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
+
+| `_tag` | Written by |
+| --- | --- |
+| `CliStatus` | Bare `nuxtseo --json` |
+| `CliVersion` | `--version --json` |
+| `CliHelp` | `--help --json` |
+| `CliConfig` | `config --json` |
+| `CliLogout` | `logout --json` |
+| `CliSiteSelection` | `sites use <site-id> --json` |
+| `CliError` | Any failure with no server body |
+
+Discriminate on `_tag`. Protocol envelopes never carry one.
+
+## Paging
+
+One invocation makes one request. The CLI never auto-pages or merges responses.
+
+Pass the reported `offset` or opaque `cursor` for another page. Never edit or
+infer a cursor. Keep server order for actions. Never re-rank merged results.
+
+## Exit codes
+
+Branch on the exit code, not message text.
+
+| Code | Meaning | Action |
+| ---: | --- | --- |
+| `0` | Success, including a closed stdout pipe | Continue |
+| `2` | Invalid input, or mutation without `--yes` | Fix arguments. Do not retry unchanged |
+| `3` | Missing, invalid, or expired authentication | Ask the user for a token |
+| `4` | Forbidden, scope, or entitlement failure | Report the plan or token blocker |
+| `5` | Conflict, stale evidence, or ambiguous Site | Re-read. Pass `--site` if ambiguous |
+| `6` | Rate limit, quota, provider outage, or timeout | Read retry metadata, then wait |
+| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID |
+| `8` | Resource or Site not found | Run `sites list` for a valid Site ID |
+| `127` | Shell cannot find `nuxtseo` | Install the CLI |
+| `130` | Interrupted or cancelled | Check whether a mutation ran before retrying |
+
+API failure details on stderr include the server code and request ID. They may
+include retry delay, policy, quota, reset time, and structured details. Keep the
+request ID when reporting a problem.
+
+Only exit `6` means the same command may work later. The SDK already retried
+HTTP 429 responses. Mutations are never retried automatically.