使用 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

# 按音视频里说过的内容搜索
linkly search "我们决定推迟" --type audio,video

# 搜索笔记而不是文件
linkly search "入职清单" --scope notes

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

--scope notes 会把结果限定在你的笔记中，并且会忽略 --library 和 --path-glob —— 这两个过滤条件会被静默丢弃，而不是报错。

查看文档大纲

linkly outline <DOC_ID>

获取文档的结构化大纲和元数据。DOC_ID 从搜索结果中获取。支持一次查看多个文档，也可以用 - 从管道读入 ID：

linkly outline id1 id2 id3

# 把搜索到的文档全部取大纲，无需写 shell 循环
linkly search "架构" --json | jq -r '.results[].doc_id' | linkly outline -

大纲功能对 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

# 在搜索到的全部文档中做 grep
linkly search "部署" --json | jq -r '.results[].doc_id' \
  | linkly grep "docker|kubernetes" -

阅读文档内容

linkly read <DOC_ID>...

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

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

# 同时输出页面中引用图片的 OCR 文本
linkly read <DOC_ID> --image-text full

# 一次读取多个文档，或用管道传入 ID
linkly read id1 id2 id3
linkly search "入职" --json | jq -r '.results[].doc_id' | linkly read -

使用 --json 时，多个文档会以 JSON Lines 格式输出 —— 每行一个对象。只传单个 ID 时仍然输出单个对象，因此现有脚本不受影响。

分页策略： 默认每次读取 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。

笔记

Linkly AI 会把简短的 Markdown 笔记保存在你的知识库目录中。它们就是普通的本地文件 —— 不会被上传 —— 并且和其他文档一样会被索引。

# 列出笔记，最新的在前
linkly list --scope notes

# 按标签过滤
linkly list --scope notes --tags project,urgent

# 写一条笔记
linkly note-save --mode create --content "记得续期证书" --tags ops

# 正文较长时用管道传入，不必写在引号里
some-command | linkly note-save --mode create --content -

编辑已有笔记需要它的 note_id 和当前 version，两者都可以从 linkly list --scope notes 的输出中获取：

linkly note-save --mode edit \
  --note-id <uuid> --base-version <version> \
  --tags ops --content "更新后的内容"

正文里的 #标签 就是笔记的标签——--tags 只能追加（删标签要从内容里删掉对应的 #标签）。0.11.0 之前的 Desktop 则是编辑时必须传 --tags 且按全量替换处理。--base-version 是并发校验：如果笔记在你读取之后被改动过，命令会以 NOTE_VERSION_CONFLICT 失败，而不是覆盖写入。笔记内容只支持受限的 Markdown 子集（段落、加粗、删除线、列表）；标题、代码、链接和表格会被拒绝。

Shell 补全

linkly completions <SHELL>

输出 bash、zsh、fish、powershell 或 elvish 的补全脚本。

zsh
bash
fish
PowerShell

mkdir -p ~/.zfunc
linkly completions zsh > ~/.zfunc/_linkly
# 如果 ~/.zshrc 里还没有，加上：
#   fpath=(~/.zfunc $fpath)
#   autoload -Uz compinit && compinit

linkly completions bash > /usr/local/etc/bash_completion.d/linkly

linkly completions fish > ~/.config/fish/completions/linkly.fish

linkly completions powershell | Out-String | Invoke-Expression

配置完成后请打开一个新的 shell。补全脚本是静态的 —— 它不会与 Linkly AI Desktop 通信，所以桌面应用未运行时也能用，也不会拖慢你的命令行提示符。

MCP 模式

linkly mcp

以 stdio MCP 服务器模式运行，将 Linkly AI 的工具暴露给 MCP 兼容的 AI 客户端。上游连接方式决定了客户端能访问到的范围：

命令	可访问范围
`linkly mcp`	本机桌面应用 —— 仅本地内容
`linkly mcp --endpoint <url>`	局域网内的桌面应用 —— 内容边界相同
`linkly mcp --remote`	云端网关 —— 本地内容以及已关联的云端知识库

--remote 是唯一能访问云端知识库的桥接模式，需要先保存 API Key（参见远程模式）。

配置 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

随时可以查看或清除已保存的 Key：

linkly auth status   # 当前使用哪个 Key、是否有效，以及你的订阅方案
linkly auth logout   # 删除本地保存的凭据

--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 格式输出（适合脚本和自动化）
`--exit-code`	所有命令	区分”没找到”（退出 1）和”执行失败”（退出 2）—— 参见退出码
`-V, --version`	—	显示 CLI 版本号
`-h, --help`	—	显示帮助信息

--endpoint、--token 和 --remote 可用于各个文档类命令（search、grep、outline、read、list、note-save、find-paths、explore、list-libraries）以及 status 和 doctor。mcp 命令接受 --endpoint 或 --remote，但不接受 --token。--json 和 --exit-code 在所有命令中可用。

退出码

默认情况下，CLI 采用惯例的两种取值：成功返回 0，失败返回 1。注意”成功”包含”什么都没找到”——搜索没有命中时仍然退出 0。加上 --exit-code 可以区分这两种情况：

退出码	含义
`0`	执行成功，且至少有一条结果
`1`	执行正常，但没有任何匹配
`2`	执行失败（连接、认证、参数错误、异常等）

# 只有搜索确实有结果时才打开报告
linkly search "季度报告" --exit-code && open-report

这个开关默认关闭，因为它改变了 1 的含义。不加时 1 表示”执行失败” —— 而这正是现有脚本所依赖的判断。

search 参数

参数	说明	默认值
`<QUERY>`	搜索关键词或短语（必填）	—
`--limit <N>`	最大返回结果数（1-50）	20
`--type <TYPES>`	按文档类型过滤（逗号分隔）：`pdf`、`docx`、`pptx`、`epub`、`md`、`txt`、`html`、`image`、`audio`、`video`	全部
`--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`（最旧优先），省略则保留相关度排序	—
`--scope <SCOPE>`	`folder` 搜索全部已索引内容；`notes` 将结果限定在笔记中，并忽略 `--library` / `--path-glob`	folder
`--tags <LIST>`	逗号分隔的笔记标签；只返回同时带有全部标签的文档	—

find-paths 参数

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

outline 参数

参数	说明	默认值
`<ID>...`	文档 ID（必填，支持多个）。传 `-` 表示从标准输入读取 ID，每行一个	—

grep 参数

参数	说明	默认值
`<PATTERN>`	正则表达式模式（必填）	—
`<DOC_ID>...`	要搜索的文档 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（必填，支持多个）。传 `-` 表示从标准输入读取 ID	—
`--offset <N>`	起始行号（从 1 开始）	1
`--limit <N>`	读取行数（最多 500）	200
`--image-text <DETAIL>`	页面中引用图片的文本详细程度：`none`（仅保留映射关系）、`abstract`（摘录）、`full`（内联完整 OCR 文本）	abstract

list 参数

参数	说明	默认值
`--scope <SCOPE>`	要列出的容器：`folder`（某目录下的已索引文件）、`library`（某个知识库的文件）或 `notes`（必填）	—
`--library <LIB>`	配合 `--scope library` 指定哪个库——库名、`local://<id>` 或 `cloud://<owner>/<slug>`（远程）	—
`--path <DIR>`	要列举的目录——本地传绝对路径，云端库传相对前缀	—
`--type <LIST>`	逗号分隔的文档类型（仅 `folder` / `library`），如 `pdf,docx`	全部
`--modified-after <DATE>`	只要这天及之后修改过的条目（仅 `folder` / `library`）。ISO 8601，如 `2026-01-01`	—
`--modified-before <DATE>`	只要这天及之前修改过的条目。格式同上	—
`--tags <LIST>`	逗号分隔的标签（仅 `notes`）；只返回同时带有全部标签的条目	—
`--limit <N>`	最大条目数（最多 200；摘要片段开启期间上限为 50）	50
`--offset <N>`	分页偏移量	0
`--sort <ORDER>`	`recent`（最新优先）、`oldest`（最旧优先）或 `name`（按名称）	recent
`--snippet` / `--no-snippet`	强制开启 / 关闭每条的摘要片段（互斥）。默认 `notes` 开、`folder` / `library` 关	按 scope

note-save 参数

参数	说明	默认值
`--mode <MODE>`	`create` 新建笔记；`edit` 重写已有笔记（需要 `--note-id` 和 `--base-version`）	—
`--content <TEXT>`	笔记正文（必填）。传 `-` 表示从标准输入读取	—
`--note-id <UUID>`	要编辑的笔记 ID，来自 `linkly list --scope notes`	—
`--base-version <HASH>`	笔记的当前版本，来自 `linkly list --scope notes`。若笔记期间被改动过则拒绝写入	—
`--tags <LIST>`	逗号分隔、要追加的标签——删标签要从内容里删掉对应的 `#标签`	—
`--app-name <NAME>`	承载这次对话的应用的显示名，会作为笔记的来源徽章展示。最长 64 字符	—

completions 参数

参数	说明	默认值
`<SHELL>`	`bash`、`zsh`、`fish`、`powershell` 或 `elvish`（必填）	—

快速开始

核心功能

接入 AI 工具

给 Agent 的指南

使用 Linkly AI Cli

Linkly AI CLI 介绍

终端搜索

MCP 桥接

安装

使用方法

检查连接状态

搜索文档

查看文档大纲

正则匹配文档内容

阅读文档内容

路径定位（find-paths）

笔记

Shell 补全

MCP 模式

更新 CLI

连接模式

本地模式（默认）

局域网模式

远程模式

参数说明

全局选项

退出码

search 参数

find-paths 参数

outline 参数

grep 参数

read 参数

list 参数

note-save 参数

completions 参数

​Linkly AI CLI 介绍

终端搜索

MCP 桥接

​安装

​使用方法

​检查连接状态

​搜索文档

​查看文档大纲

​正则匹配文档内容

​阅读文档内容

​路径定位（find-paths）

​笔记

​Shell 补全

​MCP 模式

​更新 CLI

​连接模式

​本地模式（默认）

​局域网模式

​远程模式

​参数说明

​全局选项

​退出码

​search 参数

​find-paths 参数

​outline 参数

​grep 参数

​read 参数

​list 参数

​note-save 参数

​completions 参数

Linkly AI CLI 介绍

安装

使用方法

检查连接状态

搜索文档

查看文档大纲

正则匹配文档内容

阅读文档内容

路径定位（find-paths）

笔记

Shell 补全

MCP 模式

更新 CLI

连接模式

本地模式（默认）

局域网模式

远程模式

参数说明

全局选项

退出码

search 参数

find-paths 参数

outline 参数

grep 参数

read 参数

list 参数

note-save 参数

completions 参数