# CLI

> 通过终端执行 Management API 脚本、为网站集合生成 TypeScript 类型，并检查 Headless 前端的设置。

> Markdown version of https://kanorio.com/zh-CN/developers/cli. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/cli.md

Kanorio CLI 为 Management API 提供命令行封装，适用于脚本与 CI 环境，并新增两项开发者工具：类型生成与 Headless 前端健康检查。

```bash
npx @kanorio/cli --help
```

## 登录

```bash
npx @kanorio/cli login --token knr_pat_...
```

令牌会以仅限拥有者访问的权限存储于 `~/.config/kanorio/config.json`。在 CI 环境中，请改为设置 `KANORIO_TOKEN`，其优先级高于存储的令牌。使用 [服务账号](https://kanorio.com/zh-CN/developers/authentication) 令牌亦可。

## 常见指令

```bash
kanorio sites list
kanorio pages list ws_example123
kanorio pages replace-sections ws_example123 pg_example456 --file sections.json
kanorio media upload ws_example123 --file hero.jpg
kanorio publish ws_example123
kanorio domains status ws_example123
```

会覆盖内容的指令会先读取资源并发送其时间戳，因此若发生冲突，系统会返回 `CONFLICT` 错误，而非覆盖他人的编辑。执行 `kanorio --help` 可查看完整列表。

## 输出与退出代码

- 加入 `--json` 参数可打印原始 API 响应（包含错误），便于编写脚本。
- 错误信息会以 `<CODE> (HTTP <status>): <message>` 格式输出至 stderr，并以 `1` 退出程序。用法错误则以 `2` 退出。
- 关于已弃用操作的警告会输出至 stderr。

## 生成类型

```bash
kanorio types --site https://s-xxxxxxxxxxxx.kanorio.com --out src/kanorio.d.ts
```

`types` 指令会读取网站的公开集合架构，并为每个集合写入 `FieldData`、`Expanded` 与 `Item` 类型，以及页面、全局变量与网站元数据的类型。当架构变更时请再次执行，或订阅 `collections.schema.changed` Webhook 以自动化此流程。

## 检查 Headless 前端

```bash
kanorio doctor --site ws_example123
```

`doctor` 指令会检查您的前端是否正确提供 sitemap、robots.txt、llms.txt、feeds、JSON-LD 与 IndexNow 密钥文件，并确认页面内容是否同步，以及浏览量与 Webhook 是否正常送达。在将域名从 Kanorio 托管网站迁移至您自己的前端之前，请加上 `--switching` 参数。