{"_id":"@sitedata-dev/cli","name":"@sitedata-dev/cli","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@sitedata-dev/cli","version":"0.1.0","description":"Official SiteData CLI for humans and AI agents","keywords":["sitedata","cli","api","oauth","seo","ai-agent"],"homepage":"https://sitedata.dev","repository":{"type":"git","url":"git+https://github.com/SiteData-DEV/sitedata-cli.git"},"bugs":{"url":"https://github.com/SiteData-DEV/sitedata-cli/issues"},"type":"module","bin":{"sitedata":"dist/bin.js"},"scripts":{"build":"node scripts/clean-dist.mjs && tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","test":"tsx --test tests/*.test.ts","check":"pnpm typecheck && pnpm test && pnpm build","release":"node scripts/release.mjs"},"engines":{"node":">=20"},"devDependencies":{"@types/node":"^24.3.0","tsx":"^4.20.5","typescript":"^5.9.2"},"packageManager":"pnpm@10.12.1","_id":"@sitedata-dev/cli@0.1.0","gitHead":"e69ddd9600fd196c5f6510a7fd4a978f88167d71","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-JLCOJmRb2vWvpZ4SVGgv1EmyCMVUQ21UgonqnVZzJtJCWnjIaznHB1upIMvWZGSjryVyqXIrkJC/fPP6q9eBlA==","shasum":"9c7bdb8b8e4a981c30dbd7ebc39f4c60205bf980","tarball":"https://registry.npmjs.org/@sitedata-dev/cli/-/cli-0.1.0.tgz","fileCount":67,"unpackedSize":198522,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDVVbQxS9hnhpiq+MFanrcmAX5/ms/P8NAL4e/WPS6y/QIgD2PEJfxJ6HY3TsHsYKr9VQeYgz2r5JsqcXn7QbVMA7k="}]},"_npmUser":{"name":"xiongxiongop","email":"86931619@qq.com"},"directories":{},"maintainers":[{"name":"xiongxiongop","email":"86931619@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_0.1.0_1788775390989_0.14167016957711276"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T10:03:10.707Z","0.1.0":"2026-09-07T10:03:11.138Z","modified":"2026-09-07T10:03:11.381Z"},"maintainers":[{"name":"xiongxiongop","email":"86931619@qq.com"}],"description":"Official SiteData CLI for humans and AI agents","homepage":"https://sitedata.dev","keywords":["sitedata","cli","api","oauth","seo","ai-agent"],"repository":{"type":"git","url":"git+https://github.com/SiteData-DEV/sitedata-cli.git"},"bugs":{"url":"https://github.com/SiteData-DEV/sitedata-cli/issues"},"readme":"# SiteData CLI\n\n[![npm version](https://img.shields.io/npm/v/@sitedata-dev/cli.svg)](https://www.npmjs.com/package/@sitedata-dev/cli)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933.svg)](https://nodejs.org/)\n\n[English](./README.md) | [中文](./README.zh.md)\n\n[SiteData](https://sitedata.dev) 官方命令行客户端，面向人类用户和 AI Agent。通过安全的 OAuth 鉴权，即可在终端中查询网站排行榜、管理网站及关键词收藏，并获得结构化输出。\n\n[安装](#安装与快速开始) · [AI Agent](#ai-agent-快速开始) · [鉴权](#鉴权) · [命令](#命令) · [进阶用法](#进阶用法) · [安全](#安全)\n\n## 为什么选择 SiteData CLI？\n\n- **面向 Agent 设计** — 命令稳定、Schema 可读取、支持 JSON 输出和明确退出码，API 调用过程中不会弹出交互式问题。\n- **能力始终同步** — 命令和参数来自 SiteData 在线 Catalog，不依赖可能过期的本地快照。\n- **浏览器登录简单** — 使用 OAuth Authorization Code + PKCE，自动打开浏览器并通过本机回调完成授权。\n- **凭证安全存储** — OAuth 凭证保存在 Windows Credential Locker、macOS Keychain 或 Linux Secret Service 中。\n- **按安装实例授权** — 每个操作系统用户下的 CLI 安装保存随机客户端标识，同一安装重新登录只替换该安装原有的会话。\n- **支持读取与写入** — GET API 使用查询参数，POST API 使用 JSON 请求正文。\n- **结构化输出** — 支持格式化 JSON、紧凑 JSON、原始响应以及仅输出响应中的 `data` 字段。\n\n## 适合哪些场景？\n\n| 你是…… | 推荐使用方式 |\n| --- | --- |\n| 终端用户 | 全局安装后运行 `sitedata login`，然后执行 API 命令。 |\n| AI 编程客户端用户 | 登录一次，让 Codex、Claude Code 等具备终端能力的 Agent 执行 `sitedata ... --output json`。 |\n| 脚本或自动化任务维护者 | 使用运行自动化任务的同一操作系统用户完成 OAuth，并通过 JSON 输出和退出码处理结果。 |\n| MCP 客户端用户 | 原生 MCP 工具调用请使用 [SiteData MCP Server](https://mcp.sitedata.dev/mcp)，CLI OAuth 与 MCP OAuth 相互独立。 |\n\n## 功能\n\n| 分类 | 能力 |\n| --- | --- |\n| 网站排行榜 | 查询完整的流量增长、Domain Rating 增长和支付流量排行榜，支持当前/历史周期及公开筛选条件。 |\n| 收藏 | 查询、新增、更新和删除网站或关键词收藏。 |\n| 收藏文件夹 | 创建、重命名、删除文件夹，并按文件夹筛选收藏。 |\n| 能力发现 | 列出当前 API Catalog，查看命令 Schema、枚举值、默认值与示例。 |\n\n服务端发布权威命令 Catalog。运行 `sitedata list` 可查看 CLI 当前可用的全部 API。\n\n## 安装与快速开始\n\n### 环境要求\n\n- Node.js 20 或更高版本\n- npm 或兼容的包管理器\n- 用于 OAuth 授权的 SiteData 账号\n\n### 安装\n\n```bash\nnpm install --global @sitedata-dev/cli\nsitedata --version\n```\n\n### 终端用户快速开始\n\n```bash\n# 1. 在浏览器中登录\nsitedata login\n\n# 2. 检查鉴权状态\nsitedata auth status\n\n# 3. 查看当前 API\nsitedata list\n\n# 4. 查询流量增长排行榜\nsitedata rankings traffic-growth --output json\n\n# 5. 查看已收藏的网站\nsitedata favorites list --kind website --output json\n```\n\n浏览器登录使用固定公共 OAuth Client `sitedata-cli`、Resource `https://sitedata.dev` 和 Scope `api:invoke`。\n\n## AI Agent 快速开始\n\n> 浏览器授权需要用户交互。Agent 不得读取、打印或复制操作系统凭据库中的凭证。\n\n```bash\n# 1. 安装\nnpm install --global @sitedata-dev/cli\n\n# 2. 请用户在浏览器中完成授权\nsitedata login\n\n# 3. 验证鉴权并发现 API\nsitedata auth status\nsitedata list --output json\n\n# 4. 查看并调用 API\nsitedata describe rankings --output json\nsitedata rankings traffic-growth --output json\nsitedata favorites list --kind all --output json\n```\n\n为了让 Agent 稳定调用，可以将以下内容加入 `AGENTS.md`、`CLAUDE.md` 或同类指令文件：\n\n```md\n需要 SiteData 排行榜或收藏数据时，使用全局安装的 `sitedata` CLI。\nAPI 命令统一添加 `--output json`。使用 `sitedata list --output json` 获取\n当前 API，使用 `sitedata describe <command> --output json` 查看参数。\n禁止读取或暴露已保存的 OAuth Token。\n```\n\nAI Agent 必须与完成 `sitedata login` 的用户运行在同一个操作系统账户下。Windows 凭证不会自动共享给 WSL、Docker、其他电脑或远程 Agent 运行环境。\n\n## 鉴权\n\nSiteData CLI 使用 OAuth Authorization Code + PKCE：\n\n```bash\nsitedata login\nsitedata auth status\nsitedata logout\n```\n\nAccess Token 即将过期时会自动刷新。退出登录时，CLI 会尝试在服务端撤销 OAuth 凭证，并始终删除本地凭证。\n\n每个安装实例保存一个以 `sd_` 开头的随机标识。同一安装重新授权时会替换原有 SiteData CLI 会话，不会撤销其他安装实例的会话。\n\n## 命令\n\n### 发现 API 和 Schema\n\n```bash\nsitedata list\nsitedata list --output json\nsitedata describe rankings\nsitedata describe favorites --output json\nsitedata rankings --help\n```\n\nCLI 从所选 API Base URL 的 `/api/v1/mcp/catalog` 加载 Catalog。如果在线 Catalog 不可用或格式无效，命令会直接失败，不会使用过期的本地定义。\n\n### 排行榜查询\n\n`rankings` 命令将 `rankingType` 作为必填参数，枚举值可以使用 kebab-case 别名：\n\n```bash\n# 当前流量增长排行榜\nsitedata rankings traffic-growth --output json\n\n# 历史 Domain Rating 增长排行榜\nsitedata rankings domain-rating-growth --period archive --month 2026-08 --output json\n\n# 按支付网关和语言筛选支付流量排行榜\nsitedata rankings payment-traffic --gateway stripe --locale en --output json\n\n# 查询公开标签中新发现的网站\nsitedata rankings traffic-growth --new-sites --tag-type category --tag-code ai --output json\n```\n\n### 收藏和文件夹\n\n`favorites` 是 POST API。必填的 `action` 可以作为第一个位置参数传入：\n\n```bash\n# 查询收藏\nsitedata favorites list --kind all --output json\nsitedata favorites list --kind website --folder-id <folder-id> --output json\n\n# 新增和更新收藏\nsitedata favorites add --kind website --domain example.com --remark Research\nsitedata favorites add --kind keyword --keyword \"ai tools\"\nsitedata favorites update --kind website --id <favorite-id> --folder-id <folder-id>\nsitedata favorites delete --kind keyword --id <favorite-id>\n\n# 管理文件夹\nsitedata favorites create-folder --name Research\nsitedata favorites rename-folder --folder-id <folder-id> --name Competitors\nsitedata favorites delete-folder --folder-id <folder-id>\n```\n\n在线 Catalog 始终是唯一事实来源。编写自动化任务前，建议运行 `sitedata describe favorites` 检查当前 action 枚举和参数。\n\n### 位置参数和参数别名\n\n必填参数既可以按名称传入，也可以在没有歧义时作为位置参数传入：\n\n```bash\nsitedata rankings --ranking-type traffic-growth\nsitedata rankings traffic-growth\n```\n\nCatalog 参数名支持 kebab-case 别名。例如 `rankingType`、`newSites` 和 `folderId` 可分别写成 `--ranking-type`、`--new-sites` 和 `--folder-id`。\n\n## 进阶用法\n\n### 输出模式\n\n```text\n--output pretty   缩进格式化 JSON（默认）\n--output json     适合 Agent 和脚本的紧凑 JSON\n--output raw      原始响应正文\n--data-only       仅输出响应中的 data 字段\n```\n\n`--data-only` 不能与 `--output raw` 同时使用。正常结果写入 stdout，错误与更新提示写入 stderr。\n\n### 全局参数\n\n```text\n    --base-url <url>       API Base URL（或 SITEDATA_BASE_URL）\n-o, --output <mode>        pretty、json 或 raw（默认：pretty）\n    --data-only            仅输出响应 data 字段\n    --timeout <seconds>     请求超时时间（默认：45 秒）\n    --no-update             本次命令跳过自动更新\n-h, --help                 显示帮助\n-V, --version              显示版本\n```\n\n### 环境变量\n\n| 变量 | 用途 |\n| --- | --- |\n| `SITEDATA_BASE_URL` | 覆盖 REST API Base URL |\n| `SITEDATA_OAUTH_ISSUER` | 开发时覆盖 OAuth Issuer |\n| `SITEDATA_OAUTH_RESOURCE` | 开发时覆盖 OAuth Resource |\n| `SITEDATA_NO_UPDATE=1` | 禁用自动更新 |\n| `SITEDATA_PACKAGE_MANAGER` | 指定全局更新所用的 `npm`、`pnpm`、`yarn` 或 `bun` |\n\n稳定版默认将 `https://sitedata.dev` 用作 API、OAuth Issuer 和 OAuth Resource。版本号包含 `-next` 时，默认使用 `https://www2.sitedata.dev` 作为 OAuth Issuer，同时保留生产 API Resource 和 Base URL。所有端点均可在本地开发时覆盖。\n\n### 自动升级\n\nCLI 会检查与当前安装版本对应的 npm 发布通道。成功检查结果缓存 1 小时；Registry 查询失败后 5 分钟重试，安装失败后 15 分钟重试。\n\n发现新版本后，CLI 使用检测到的包管理器执行全局更新。当前命令继续使用已加载的旧版本，下次运行开始使用新版本。多个进程并发调用时，更新锁保证只有一个进程执行安装。\n\n自动更新失败只会向 stderr 输出警告，原命令仍会继续执行。`CI=true` 时默认禁用自动更新。\n\n```bash\nsitedata update --check  # 立即检查，不安装\nsitedata update          # 立即检查并安装\nsitedata --no-update rankings traffic-growth\n```\n\n`SITEDATA_NO_UPDATE_CHECK=1` 作为旧版兼容开关仍然有效。\n\n### 退出码\n\n| 退出码 | 含义 |\n| --- | --- |\n| `0` | 成功 |\n| `1` | API、鉴权、网络或运行时错误 |\n| `2` | 命令或参数使用错误 |\n\n## 开发\n\n```bash\npnpm install\npnpm check\nnpm pack --dry-run\n```\n\n## 安全\n\n- OAuth 使用 Authorization Code + PKCE，公共客户端不包含 Client Secret。\n- 回调服务器只监听 `127.0.0.1` 的随机端口。\n- OAuth Token 使用操作系统原生凭据服务保存，不会写入项目明文配置。\n- 正常命令输出和错误信息不会包含凭证。\n- CLI OAuth Token 使用 REST API Audience 和 `api:invoke` Scope，不能作为 MCP Token 使用。\n- AI Agent 可能做出错误决策。请审查可能修改收藏或暴露私有业务数据的命令，并只授予必要权限。\n\n## 相关链接\n\n- [SiteData](https://sitedata.dev)\n- [SiteData MCP](https://mcp.sitedata.dev/mcp)\n- [npm 上的 SiteData CLI](https://www.npmjs.com/package/@sitedata-dev/cli)\n- [源代码](https://github.com/SiteData-DEV/sitedata-cli)\n- [问题反馈](https://github.com/SiteData-DEV/sitedata-cli/issues)\n","readmeFilename":"README.zh.md","_rev":"1-cd46fc18b88e682d3c3e56de608bb9f5"}