> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# CLI 使用教程

我们提供了 `@rsdoctor/cli` 让你可以在本地通过 CLI 程序来使用 Rsdoctor 提供的功能

:::tip
请为 `@rsdoctor/cli` 和 `@rsdoctor/core` 使用相同的版本。
:::

## 安装 @rsdoctor/cli

:::tip

- 可以使用非安装方式，使用 `npx @rsdoctor/cli <command> [options]`。

:::


```sh [npm]
npm add @rsdoctor/cli -D
```

```sh [yarn]
yarn add @rsdoctor/cli -D
```

```sh [pnpm]
pnpm add @rsdoctor/cli -D
```

```sh [bun]
bun add @rsdoctor/cli -D
```

```sh [deno]
deno add npm:@rsdoctor/cli -D
```

## 命令使用

```bash

rsdoctor <command> [options]

```

`@rsdoctor/cli` 目前提供了以下几个命令对应不同的功能：

### analyze 命令

`analyze` 命令主要是用于在**本地**加载 [manifest.json](/zh/config/options/term.md) 并且无需再次构建直接启动 Rsdoctor 的分析报告页面。

```bash
rsdoctor analyze --profile <manifestFile>
```

**参数定义**

- `manifestFile` 即为 [manifest.json](/zh/config/options/term.md) 的路径（支持本地路径）

**使用示例**

```bash
rsdoctor analyze --profile "./dist/.rsdoctor/manifest.json"
```

### bundle-diff 命令

`bundle-diff` 命令用于在**本地**加载**两份** [manifest.json](/zh/config/options/term.md#manifestjson)，并对比分析两次构建产物。默认情况下，该命令会在浏览器中打开 Rsdoctor 的 [Bundle Diff](/zh/guide/usage/bundle-diff.md) 页面。使用 `--json [path]` 可以直接生成 JSON 报告，而不会启动报告服务器或打开浏览器。

```bash
rsdoctor bundle-diff --baseline <baselineManifestJsonPath> --current <currentManifestJsonPath>
```

**参数定义**

- `--baseline <path>`：作为**基准**的 [manifest.json](/zh/config/options/term.md#manifestjson) 路径或在线 URL。
- `--current <path>`：作为**当前构建**的 [manifest.json](/zh/config/options/term.md#manifestjson) 路径或在线 URL。
- `--json [path]`：生成 JSON 差异报告，默认输出路径为 `rsdoctor-diff.json`。

**在浏览器中打开报告**

```bash
rsdoctor bundle-diff --baseline="baseline/.rsdoctor/manifest.json" --current="current/.rsdoctor/manifest.json"
```

**生成 JSON 报告**

```bash
rsdoctor bundle-diff \
  --baseline="baseline/.rsdoctor/manifest.json" \
  --current="current/.rsdoctor/manifest.json" \
  --json="result.json"
```

JSON 报告包含 assets、modules 和 packages 的差异数据，可用于 CI 流程或生成 Pull Request 评论。

## Node API

我们在 `@rsdoctor/cli` 中提供了 Node.js API，可以让你在 Node.js 运行时进行调用。

**引入模块**

```js
import { execute } from '@rsdoctor/cli';
```

**execute()**

`execute` 异步函数是 Rsdoctor CLI 的执行函数，通过调用 `execute` 函数就会自动解析 [process.argv](https://nodejs.org/dist/latest-v22.x/docs/api/process.html#processargv)，然后调用不同的命令。

**execute('analyze', \{...})**

如果你需要通过 Node.js API 直接执行 [analyze 命令](#analyze-命令)，则可以通过如下方式调用：

```ts
execute('analyze', {
  profile: 'input the manifest.json path or url',
}).then((sdk) => {
  console.log('execute "analyze" command success');
  // you can stop the Rsdoctor's dev-server by calling the sdk'api below:
  // sdk.dispose();
});
```