CLI 命令参考

@clarify-labs/cli 提供 clarify 命令，封装开发服务器、静态构建和项目初始化。用户不需要创建 Vite 配置文件。

安装

推荐把 CLI 安装为项目开发依赖，这样 CLI 版本会跟随仓库一起被锁定和 Review：

pnpm add -D @clarify-labs/cli

然后通过 pnpm exec 运行：

pnpm exec clarify init
pnpm exec clarify dev
pnpm exec clarify check
pnpm exec clarify build

或者在 package.json 中添加脚本：

{
  "scripts": {
    "dev": "clarify dev",
    "build": "clarify build"
  }
}

如果只是临时体验，也可以全局安装后直接运行 clarify dev / clarify build，但团队项目建议优先使用项目本地依赖。

`clarify init`

创建一个 Clarify 项目骨架，并自动更新 package.json 中的 dev 和 build 脚本。

pnpm exec clarify init

默认情况下，clarify init 会生成或更新以下内容：

clarify.ts
source/index.mdx
package.json 中的 dev / build 脚本
@clarify-labs/cli 开发依赖

如果希望初始化完成后立即安装依赖，可以使用：

pnpm exec clarify init --install

未使用 --install 时，命令会提示下一步操作，例如：

cd <project-root>
pnpm install
clarify dev

常用选项：

选项	说明	默认值
`--root <dir>`	项目根目录	当前目录
`--content <dir>`	内容目录	`source`
`--template <name>`	`minimal`、`standard` 或 `complete` 模板	`standard`
`--force`	覆盖已存在的初始化文件	`false`
`--install`	初始化后安装依赖	`false`

模板适用场景：

模板	适合场景
`minimal`	只想快速验证 Clarify 或接入已有内容目录
`standard`	新建一个常规文档站，包含推荐的基础结构
`complete`	学习完整能力，查看导航、组件、OpenAPI 和发布配置示例

`clarify dev`

启动本地文档开发服务器。

pnpm exec clarify dev

常用选项：

选项	说明	默认值
`--root <dir>`	项目根目录	当前目录
`--content <dir>`	内容目录	`source`
`--host [host]`	监听地址	Vite 默认值
`--port <port>`	端口号	Vite 默认值
`--open [path]`	启动后打开浏览器	`false`

示例：

pnpm exec clarify dev --port 5173 --open

`clarify build`

构建可部署的静态站点。

pnpm exec clarify build

常用选项：

选项	说明	默认值
`--root <dir>`	项目根目录	当前目录
`--content <dir>`	内容目录	`source`
`--output <dir>`	输出目录	`output`

示例：

pnpm exec clarify build --output dist

配置了 siteUrl 后，构建会额外输出 sitemap.xml 和 robots.txt。

`clarify check`

在不产出构建文件的情况下检查文档项目。

pnpm exec clarify check

check 会报告缺失的内容目录、重复路由、无效 OpenAPI 描述文件、损坏的本地 Markdown 链接，以及 i18n fallback 页面。

常用选项：

选项	说明	默认值
`--root <dir>`	项目根目录	当前目录
`--content <dir>`	内容目录	`source`
`--strict`	将 warning 也视为失败	`false`
`--format <format>`	`text` 或 `json`	`text`

配置文件

推荐使用 clarify.ts 作为唯一项目配置入口。它既可以配置站点展示字段，也可以配置构建期扩展能力：

import { defineConfig } from '@clarify-labs/cli'

export default defineConfig({
  title: 'Clarify Docs',
  description: 'Documentation powered by Clarify',
  theme: { preset: 'default' },
  tabs: [
    {
      tab: 'Docs',
      icon: 'BookOpen',
      pages: 'FileTree',
    },
  ],
  plugins: [
    // searchPlugin(),
    // translatePlugin(),
  ],
  ssg: {
    failOnError: true,
  },
})

Clarify 会按以下优先级查找配置文件：

clarify.ts > clarify.js > clarify.json

clarify.json 适合不需要插件函数的简单项目；需要插件或更强类型提示时使用 clarify.ts。

配置优先级

CLI 选项用于控制运行时路径和输出目录，配置文件用于控制站点展示和构建期扩展。优先级为：

CLI 选项 > clarify.ts/js/json > 默认值

帮助与版本

clarify --help
clarify --version