使用 Linkly AI Cli

Linkly AI CLI 介绍

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

终端搜索

在命令行中直接搜索你的文档，适合开发者和极客用户

MCP 桥接

以 stdio MCP 模式运行，让 Claude Desktop、Cursor 等 AI 工具调用 Linkly AI

安装

macOS / Linux
Windows
Cargo

在终端中运行：

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

或通过 Homebrew 安装：

brew tap LinklyAI/tap
brew install linkly

在 PowerShell 中运行：

irm https://updater.linkly.ai/cli/install.ps1 | iex

从 crates.io 安装（需要 Rust 工具链）：

cargo install linkly-ai-cli

安装完成后，验证安装：

linkly --version

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

使用方法

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

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

检查连接状态

linkly status

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

搜索文档

linkly search "关键词或短语"

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

# 限制返回数量（默认 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

--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 + 向量混合的相关度排序。

查看文档大纲

linkly outline <DOC_ID>

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

linkly outline id1 id2 id3

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

正则匹配文档内容

linkly grep <PATTERN> <DOC_ID>

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

# 在文档中查找模式
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

阅读文档内容

linkly read <DOC_ID>

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

# 从第 50 行开始，读取 100 行
linkly read <DOC_ID> --offset 50 --limit 100

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

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）

linkly find-paths --patterns <关键词,关键词,...>

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

# 第 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 关系做子串匹配。建议一次传入多个变体（中英对照、应用真实命名等），最大化首次召回率：

linkly find-paths --patterns Notion,notion,笔记
linkly find-paths --patterns Slack,slack --library work-notes

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

MCP 模式

linkly mcp

以 stdio MCP 服务器模式运行，将 Linkly AI 的工具暴露给 MCP 兼容的 AI 客户端。 配置 Claude Desktop 等本地 AI 应用： 将以下内容添加到 Claude Desktop 等应用的配置文件中：

macOS / Linux
Windows

编辑 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

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

Name: linkly-ai
Command: linkly mcp

更新 CLI

linkly self-update

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

连接模式

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

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

本地模式（默认）

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

linkly search "机器学习"
linkly status

局域网模式

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

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 获取）：

linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

linkly search "机器学习" --remote
linkly status --remote

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

参数说明

全局选项

选项	适用范围	说明
`--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`	—	显示帮助信息

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

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

快速开始

进阶使用

使用 Linkly AI Cli

Linkly AI CLI 介绍

终端搜索

MCP 桥接

安装

使用方法

检查连接状态

搜索文档

查看文档大纲

正则匹配文档内容

阅读文档内容

路径定位（find-paths）

MCP 模式

更新 CLI

连接模式

本地模式（默认）

局域网模式

远程模式

参数说明

全局选项

search 参数

find-paths 参数

outline 参数

grep 参数

read 参数

​Linkly AI CLI 介绍

终端搜索

MCP 桥接

​安装

​使用方法

​检查连接状态

​搜索文档

​查看文档大纲

​正则匹配文档内容

​阅读文档内容

​路径定位（find-paths）

​MCP 模式

​更新 CLI

​连接模式

​本地模式（默认）

​局域网模式

​远程模式

​参数说明

​全局选项

​search 参数

​find-paths 参数

​outline 参数

​grep 参数

​read 参数

Linkly AI CLI 介绍

安装

使用方法

检查连接状态

搜索文档

查看文档大纲

正则匹配文档内容

阅读文档内容

路径定位（find-paths）

MCP 模式

更新 CLI

连接模式

本地模式（默认）

局域网模式

远程模式

参数说明

全局选项

search 参数

find-paths 参数

outline 参数

grep 参数

read 参数