> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Linkly AI Cli

> 介绍如何使用 Linkly AI CLI，获得更高的灵活性和更极客的体验。

## Linkly AI CLI 介绍

Linkly AI CLI 是一个命令行工具，通过连接 Linkly AI Desktop 的 MCP 服务，让你在终端中搜索、浏览和阅读本地文档。它同时也是 AI Agent（如 Claude Desktop、Cursor）与 Linkly AI 之间的桥梁。

<CardGroup cols={2}>
  <Card title="终端搜索" icon="terminal" iconType="duotone">
    在命令行中直接搜索你的文档，适合开发者和极客用户
  </Card>

  <Card title="MCP 桥接" icon="plug" iconType="duotone">
    以 stdio MCP 模式运行，让 Claude Desktop、Cursor 等 AI 工具调用 Linkly AI
  </Card>
</CardGroup>

## 安装

<Tabs>
  <Tab title="macOS / Linux" icon="apple">
    在终端中运行：

    ```bash theme={null}
    curl -sSL https://updater.linkly.ai/cli/install.sh | sh
    ```

    或通过 Homebrew 安装：

    ```bash theme={null}
    brew tap LinklyAI/tap
    brew install linkly
    ```
  </Tab>

  <Tab title="Windows" icon="windows">
    在 PowerShell 中运行：

    ```powershell theme={null}
    irm https://updater.linkly.ai/cli/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Cargo" icon="box">
    从 [crates.io](https://crates.io/crates/linkly-ai-cli) 安装（需要 Rust 工具链）：

    ```bash theme={null}
    cargo install linkly-ai-cli
    ```
  </Tab>
</Tabs>

安装完成后，验证安装：

```bash theme={null}
linkly --version
```

<Note>
  默认情况下，CLI 通过 `~/.linkly/port`
  文件自动发现并连接本地桌面应用。你也可以通过局域网或云隧道连接远程设备 —
  参见下方[连接模式](#连接模式)。
</Note>

## 使用方法

CLI 遵循 **search → grep 或 outline → read** 的渐进式工作流：先搜索找到目标文档，再用 grep 定位模式或查看大纲了解结构，最后阅读具体内容。当用户描述的容器（"在我微信里"、"Notion 笔记里"）真实路径未知时，可在 `search` 之前先调用 `find-paths` 定位。

<Note>
  每条成功的命令输出末尾都会带一行 `[meta] now=2026-05-08T...Z` 的 UTC
  时间戳（JSON 模式则是顶层 `_meta.now` 字段）。这是 desktop 提供给 AI
  助理用来推算"上个月"等相对时间的元信息，对人类用户而言可以忽略；脚本处理时建议过滤掉最后一行再做后续解析。
</Note>

### 检查连接状态

```bash theme={null}
linkly status
```

返回 Linkly AI Desktop 的运行状态、版本号、已索引文档数量和索引状态。

### 搜索文档

```bash theme={null}
linkly search "关键词或短语"
```

搜索你的本地文档，返回最相关的结果列表，包含标题、路径、匹配度和内容摘要。

**常用参数：**

```bash theme={null}
# 限制返回数量（默认 20，最多 50）
linkly search "API 设计" --limit 5

# 按文档类型过滤
linkly search "会议纪要" --type pdf,docx

# 输出 JSON 格式（适合脚本处理）
linkly search "预算报告" --json

# 限定时间窗口（2024 年 Q3 的季度报告）
linkly search "季度报告" --modified-after 2024-07-01 --modified-before 2024-09-30

# 按时间排序（"最新的"、"最旧的"，没有具体范围时用）
linkly search "周会纪要" --time-sort newest --limit 5
```

<Tip>
  `--modified-after` / `--modified-before` 接受 ISO 8601 UTC 格式，可以是日期
  `2024-01-01`（视为 `00:00:00Z`）或完整 RFC 3339 时间戳
  `2024-01-01T00:00:00Z`。`--time-sort` 可选 `newest` / `oldest`，缺省则保留
  BM25 + 向量混合的相关度排序。
</Tip>

### 查看文档大纲

```bash theme={null}
linkly outline <DOC_ID>
```

获取文档的结构化大纲和元数据。`DOC_ID` 从搜索结果中获取。支持一次查看多个文档：

```bash theme={null}
linkly outline id1 id2 id3
```

<Tip>
  大纲功能对 Markdown、DOCX、PowerPoint (PPTX) 和 EPUB
  文档效果最好，这些格式的标题结构可以被解析。对于纯文本或无书签的
  PDF，建议直接使用 `read` 命令。
</Tip>

### 正则匹配文档内容

```bash theme={null}
linkly grep <PATTERN> <DOC_ID>
```

在指定文档中搜索正则表达式模式匹配，用于查找特定文本（术语、人名、日期、标识符等）：

```bash theme={null}
# 在文档中查找模式
linkly grep "useState" 456

# 大小写不敏感搜索，带上下文行
linkly grep "error|warning" 1044 -C 3 -i

# 仅统计匹配数量
linkly grep "TODO" 591 --mode count

# 分页浏览匹配（跳过前 20 个，显示下 20 个）
linkly grep "import" 302 --offset 20 --limit 20
```

### 阅读文档内容

```bash theme={null}
linkly read <DOC_ID>
```

阅读文档的完整内容，输出带有行号的文本。对于长文档，可以分页阅读：

```bash theme={null}
# 从第 50 行开始，读取 100 行
linkly read <DOC_ID> --offset 50 --limit 100
```

**分页策略：** 默认每次读取 200 行（最多 500 行）。对于长文档，通过调整 `--offset` 逐步读取：

```bash theme={null}
linkly read <DOC_ID> --offset 1 --limit 200    # 第 1-200 行
linkly read <DOC_ID> --offset 201 --limit 200  # 第 201-400 行
linkly read <DOC_ID> --offset 401 --limit 200  # 第 401-600 行
```

### 路径定位（find-paths）

```bash theme={null}
linkly find-paths --patterns <关键词,关键词,...>
```

按关键词在已索引文档的**文件路径**上做模糊匹配，聚合到文件夹粒度，返回最匹配的若干候选目录。其定位是 `search` 的辅助工具：当用户描述容器名（"在我的微信里"、"在 Notion 笔记里"）但你不知道这个容器在磁盘上的真实路径时，先用 `find-paths` 探测真实路径，再把它作为 `search` 的 `--path-glob` 参数。当目录名含 glob 元字符（`* ? [`）时，可直接使用返回的 `path_glob` 字段——它已转义，能字面匹配该目录。

**典型用法（两步工作流）：**

```bash theme={null}
# 第 1 步：定位真实路径
linkly find-paths --patterns WeChat,微信,wxid --limit 5
# 假设返回 .../com.tencent.xinWeChat/Data/Documents/xwechat_files (940 文件)

# 第 2 步：在该容器下按内容搜索
linkly search "购物订单" --path-glob "*xinWeChat*"
```

**多变体匹配：** `--patterns` 接受逗号分隔的多个关键词，工具内部会以 OR 关系做子串匹配。**建议一次传入多个变体**（中英对照、应用真实命名等），最大化首次召回率：

```bash theme={null}
linkly find-paths --patterns Notion,notion,笔记
linkly find-paths --patterns Slack,slack --library work-notes
```

<Tip>
  `find-paths`
  是"找文件夹"工具，不是"找文件"工具：仅当关键词命中**目录段**才计入；如果关键词只命中文件名段（"孤儿文件"），会被静默丢弃。如果某个查询返回
  0 个目录但你确认有匹配文件，应回退到直接用 `linkly search`。
</Tip>

### MCP 模式

```bash theme={null}
linkly mcp
```

以 stdio MCP 服务器模式运行，将 Linkly AI 的工具暴露给 MCP 兼容的 AI 客户端。

**配置 Claude Desktop 等本地 AI 应用：**

将以下内容添加到 Claude Desktop 等应用的配置文件中：

<Tabs>
  <Tab title="macOS / Linux">
    编辑 `~/.config/Claude/claude_desktop_config.json`：

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "command": "linkly",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    编辑 `%APPDATA%\Claude\claude_desktop_config.json`：

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "command": "linkly",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

**配置 Cursor：**

在 Cursor 中打开 Settings → MCP Servers → Add Server，添加：

* Name: `linkly-ai`
* Command: `linkly mcp`

### 更新 CLI

```bash theme={null}
linkly self-update
```

自动检查并更新到最新版本。CLI 在每次启动时也会在后台检查更新，如有新版本会提示你运行此命令。

## 连接模式

CLI 支持三种方式连接你的 Linkly AI 知识库：

| 模式      | 参数                                 | 工作方式                                        |
| ------- | ---------------------------------- | ------------------------------------------- |
| **本地**  | *（默认，无需额外参数）*                      | 通过 `~/.linkly/port` 自动发现桌面应用                |
| **局域网** | `--endpoint <url> --token <token>` | 直连局域网内的其他设备                                 |
| **远程**  | `--remote`                         | 通过 `https://mcp.linkly.ai` 云隧道连接，需要 API Key |

### 本地模式（默认）

无需额外参数，CLI 自动读取 `~/.linkly/port` 发现运行中的桌面应用：

```bash theme={null}
linkly search "机器学习"
linkly status
```

### 局域网模式

连接局域网内其他设备上的 Linkly AI 实例。Token 可在桌面应用 **设置 → MCP** 中找到：

```bash theme={null}
linkly search "报告" --endpoint http://192.168.1.100:60606/mcp --token your_lan_token
linkly status --endpoint http://192.168.1.100:60606/mcp --token your_lan_token
```

### 远程模式

通过云隧道从任何地方连接你的知识库。首先保存 API Key（从 [linkly.ai/dashboard](https://linkly.ai/dashboard) 获取）：

```bash theme={null}
linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

然后在任意命令中使用 `--remote`：

```bash theme={null}
linkly search "机器学习" --remote
linkly status --remote
```

<Warning>
  `--endpoint` 和 `--token` 必须一起使用，用于局域网访问，不能与 `--remote`
  同时使用。远程访问请使用 `linkly auth set-key` 保存 API Key。
</Warning>

## 参数说明

### 全局选项

| 选项                 | 适用范围 | 说明                                                                |
| ------------------ | ---- | ----------------------------------------------------------------- |
| `--endpoint <URL>` | 局域网  | 连接指定的 MCP 端点（例如 `http://192.168.1.100:60606/mcp`），需同时指定 `--token` |
| `--token <token>`  | 局域网  | 局域网认证 Bearer Token（必须与 `--endpoint` 同时使用，与 `--remote` 冲突）         |
| `--remote`         | 远程   | 通过 `https://mcp.linkly.ai` 云隧道连接（与 `--endpoint` 冲突）               |
| `--json`           | 所有命令 | 以 JSON 格式输出（适合脚本和自动化）                                             |
| `-V, --version`    | —    | 显示 CLI 版本号                                                        |
| `-h, --help`       | —    | 显示帮助信息                                                            |

<Tip>
  `--endpoint`、`--token` 和 `--remote` 在 `search`、`grep`、`outline`、`read`
  和 `status` 命令中可用。`--endpoint`（不带 `--token`）也可在 `mcp`
  命令中使用。`--json` 在所有命令中可用。
</Tip>

### search 参数

| 参数                        | 说明                                                                      | 默认值 |
| ------------------------- | ----------------------------------------------------------------------- | --- |
| `<QUERY>`                 | 搜索关键词或短语（必填）                                                            | —   |
| `--limit <N>`             | 最大返回结果数（1-50）                                                           | 20  |
| `--type <TYPES>`          | 按文档类型过滤（逗号分隔，如 `pdf,md,docx,epub`）                                      | 全部  |
| `--library <NAME>`        | 限定在某个知识库内搜索                                                             | —   |
| `--path-glob <PATTERN>`   | 按文件路径过滤；对路径做子串匹配（可出现在任意位置，无需两端加 `*`）。当真实路径未知时，先调 `linkly find-paths` 获取 | —   |
| `--modified-after <ISO>`  | 修改时间下界（含），ISO 8601 UTC 格式：日期 `2024-01-01` 或完整 `2024-01-01T00:00:00Z`    | —   |
| `--modified-before <ISO>` | 修改时间上界（含），格式同 `--modified-after`                                        | —   |
| `--time-sort <MODE>`      | 时间排序：`newest`（最新优先）/ `oldest`（最旧优先），省略则保留相关度排序                          | —   |

### find-paths 参数

| 参数                  | 说明                                                                          | 默认值 |
| ------------------- | --------------------------------------------------------------------------- | --- |
| `--patterns <LIST>` | 关键词列表（逗号分隔，必填）。多个关键词之间是 OR 关系，建议一次传多个变体（中英对照、应用真实命名等）。ASCII 大小写不敏感；CJK 字面匹配 | —   |
| `--library <NAME>`  | 限定在某个知识库内查找                                                                 | —   |
| `--limit <N>`       | 最大候选目录数（1-50）                                                               | 10  |

### outline 参数

| 参数        | 说明             | 默认值 |
| --------- | -------------- | --- |
| `<ID...>` | 文档 ID（必填，支持多个） | —   |

### grep 参数

| 参数                   | 说明                                                 | 默认值     |
| -------------------- | -------------------------------------------------- | ------- |
| `<PATTERN>`          | 正则表达式模式（必填）                                        | —       |
| `<DOC_ID>`           | 文档 ID（必填）                                          | —       |
| `-C, --context`      | 匹配行前后各 N 行上下文                                      | 3       |
| `-B, --before`       | 匹配行前 N 行上下文                                        | —       |
| `-A, --after`        | 匹配行后 N 行上下文                                        | —       |
| `-i`                 | 大小写不敏感匹配                                           | —       |
| `--mode`             | 输出模式：`content` 或 `count`                           | content |
| `--limit`            | 最大匹配数（最多 100）                                      | 20      |
| `--offset`           | 跳过匹配数（用于分页）                                        | 0       |
| `--fuzzy-whitespace` | 模糊空白匹配：`true` 强制开启，`false` 强制关闭，省略则自动（PDF 开启，其他关闭） | 自动      |

### read 参数

| 参数             | 说明           | 默认值 |
| -------------- | ------------ | --- |
| `<ID>`         | 文档 ID（必填）    | —   |
| `--offset <N>` | 起始行号（从 1 开始） | 1   |
| `--limit <N>`  | 读取行数（最多 500） | 200 |