跳转到主要内容

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 Desktop 的 MCP 服务，让你在终端中搜索、浏览和阅读本地文档。它同时也是 AI Agent（如 Claude Desktop、Cursor）与 Linkly AI 之间的桥梁。

终端搜索

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

MCP 桥接

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

​
安装

在终端中运行：
curl -sSL https://updater.linkly.ai/cli/install.sh | sh
或通过 Homebrew 安装：
brew tap LinklyAI/tap
brew install linkly
安装完成后，验证安装： 
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 文档效果最好，这些格式的标题结构可以被解析。对于纯文本或无书签的 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 参数。 典型用法（两步工作流）： 
# 第 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 等应用的配置文件中：
编辑 ~/.config/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）全部
--library <NAME>限定在某个知识库内搜索—
--path-glob <PATTERN>按文件路径过滤（SQLite GLOB 语法）。当真实路径未知时，先调 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 或 countcontent
--limit最大匹配数（最多 100）20
--offset跳过匹配数（用于分页）0
--fuzzy-whitespace模糊空白匹配：true 强制开启，false 强制关闭，省略则自动（PDF 开启，其他关闭）自动

​
read 参数

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