Skip to content

Lionote CLI 使用说明

Lionote

3031字约10分钟

CLIAI Agent自动化

2026-08-27

Lionote CLI 是随 Lionote 桌面版提供的命令行工具。它让用户、脚本和具备本机终端权限的 AI Agent 可以读取、搜索、新建和修改本地笔记。

如何使用

  • 你可以直接告诉你的Agent: “帮我用Lionote创建一篇名字为xxxx的新笔记",如果你的 Agent 够聪明,他会自动查找到本地的Lionote CLI。
  • 如果你的 Agent 无法自动识别的到本地的 Lionote CLI,你可以参考下面的 【下载 Lionote Skill】,并手动放到 Agent的 SKILLS目录中。

下载 Lionote Skill

下载 Lionote SKILL.md 或 下载 lionote-skill.zip

下载后,创建名为 lionote 的子目录,并将文件保存为 SKILL.md。重新启动或新建 Agent 会话后,Agent 才会加载该 Skill。

  • WorkBuddy:在软件的 【专家·技能·连接器】-> 【技能】-> 【搜索 Lionote】安装 或 【上传技能】处上传此zip包
  • Codex(Windows):C:\Users\<用户名>\.codex\skills\lionote\SKILL.md
  • Codex(macOS/Linux):~/.codex/skills/lionote/SKILL.md
  • Claude Code(当前项目):<项目目录>/.claude/skills/lionote/SKILL.md
  • Claude Code(所有项目):~/.claude/skills/lionote/SKILL.md

其他支持 Agent Skills 的工具也遵循相同结构:<该 Agent 的 skills 目录>/lionote/SKILL.md。Skill 只告诉 Agent 如何安全调用 CLI;使用前仍需下载并安装 Lionote,且 lionote-cli 必须能通过系统 PATH 执行。

开始使用

以下说明对应 3.9.8 分支的桌面版 CLI。CLI 已支持笔记双链,包括正文、思维导图和流程图节点中的引用,以及反向引用的查询、添加和移除。

各平台的使用条件

平台首次使用App 运行时App 未运行时
macOS在设置中开启「命令行工具」,并完成终端注册由 App 处理 CLI 命令需要启动 App 后才能处理;命令入口会尝试自动启动 App 并等待就绪
Windows安装桌面版后重新打开终端或 Agent自动连接 App 执行命令,并刷新笔记CLI 独立读写本地笔记,不会启动 App
Linux安装包含 CLI 的桌面版,并配置命令入口与 PATHCLI 独立执行,写入后通知 App 刷新CLI 独立读写本地笔记,无需启动 App

普通用户无需安装 Dart 或 Flutter。完成下方对应平台的配置后,在新的终端窗口中检查:

lionote-cli --help
lionote-cli doctor --json

命令应通过系统 PATH 调用,不要在脚本或 Agent 提示词中写死软件安装路径。刚安装或调整 PATH 后,请重新打开终端、Codex 或其他 Agent 会话。

Windows:安装后即可使用,App 开启或关闭均可使用

安装器会将实际安装目录加入当前用户的 PATH。重新打开 PowerShell 或 Agent 后,可以运行:

lionote-cli.exe doctor --json

Windows 无需额外开启 CLI 设置。App 运行时,CLI 自动连接当前用户的 App,由 App 保存当前编辑、执行命令并刷新视图;App 未运行时,CLI 独立处理本地笔记。正常写入后无需重启 Lionote。

macOS:开启功能并配置终端

  1. 打开 Lionote,在设置中开启「命令行工具」。
  2. 点击「配置终端命令」,复制配置命令,在 macOS「终端」中执行一次。注册码五分钟内有效,使用一次即失效;过期后请回到设置重新获取。
  3. 重新打开终端或 AI 工具,执行 lionote-cli doctor --json 验证。

macOS 的笔记命令需要由运行中的 Lionote App 处理,请保持 App 运行且「命令行工具」已开启。 若 App 尚未运行,命令入口会尝试自动启动它并等待就绪;启动或连接失败时,请先手动打开 Lionote 再调用。

配置会创建用户级命令 ~/.local/bin/lionote-cli,并按需为 zsh 或 bash 配置 PATH;其他 Shell 请按终端提示配置。关闭「命令行工具」会撤销已有授权,再次开启后需重新配置终端命令。

macOS 商店版只操作 App 当前账户,不支持 --data-dir、--db 或 --allow-other-library。下文含目录或数据库覆盖参数的示例仅适用于 Windows/Linux 独立 CLI;macOS 商店版请省略这些参数。

Linux:安装命令入口与注意事项

使用与系统架构匹配的安装包(x64 或 arm64)。包含 CLI 的 Release/Profile bundle 中提供 lionote-cli 和 install-cli.sh,解压后也可直接运行:

"/实际安装目录/lionote-cli" doctor --json

需要通过稳定命令名调用时,运行 bundle 内的安装脚本:

bash "/实际安装目录/install-cli.sh"

默认在 /usr/local/bin/lionote-cli 创建符号链接,目录不可写时会通过 sudo 请求权限。若希望安装到用户目录,可改用:

LIONOTE_CLI_BIN_DIR="$HOME/.local/bin" bash "/实际安装目录/install-cli.sh"

使用前请注意:

  • 确认 ~/.local/bin 已加入终端或 Agent 的 PATH,并重新打开相关会话。
  • 安装脚本创建的是符号链接,请将安装目录保留在固定位置;移动、删除或更换 bundle 路径后,需要重新运行安装脚本。
  • 若解压后 CLI 提示没有执行权限,可先运行 chmod +x "/实际安装目录/lionote-cli"。
  • 使用运行 Lionote 的同一个系统用户执行 CLI,避免用 sudo lionote-cli 读取到另一用户的配置。
  • 首次使用建议先打开 Lionote,完成账户和存储目录配置,再执行 doctor --json 核对。之后 CLI 无需 App 运行即可使用;App 正在运行时,写入会发送本地刷新通知。避免在 App 和 CLI 中同时修改同一篇笔记。

数据目录与数据库

CLI 默认使用桌面端的正式存储配置和当前账户。推荐先让 CLI 自动定位:

lionote-cli doctor --json

Windows/Linux 的数据库在未登录时通常为 db.json,登录后为 <账户>-db.json。CLI 会核对当前账户,不会按文件修改时间选择数据库;自动定位失败时,请先检查 App 的账户和存储设置。

确需显式指定当前笔记库时,Windows/Linux 可以使用以下参数,并再次核对 writeSafe 和实际保存位置:

lionote-cli --data-dir "<Lionote 数据目录>" --db "<账户>-db.json" list --json

指定目录或数据库不会绕过当前账户校验;macOS 商店版直接跟随 App 当前账户,请省略这些参数。

先检查本机状态

lionote-cli --version
lionote-cli capabilities --json
lionote-cli doctor --json

doctor 会显示正在使用的数据目录、数据库、desktopRunning 和 writeSafe。写操作以 writeSafe 为准:只有返回 writeSafe: true 时才执行写入;desktopRunning 仅表示桌面端是否运行,不代表禁止写入。

常用命令

示例中的 <noteId>、<parentNoteId> 和 <Lionote 数据目录> 需要替换为实际值。建议脚本和 Agent 始终使用命令级 --json,便于稳定解析结果和错误。

列出、读取与搜索

lionote-cli list --json
lionote-cli read <noteId> --json
lionote-cli search --query "会议" --limit 20 --json

search 会搜索笔记标题、摘要和标签。需要纯正文时,可使用 read <noteId> --plain。

新建笔记

lionote-cli create --title "AI 生成的笔记" --content "这里是正文" --json
lionote-cli create --parent <parentNoteId> --title "子笔记" --content "正文" --json

长内容可以从文件或标准输入读取:

lionote-cli create --title "导入内容" --file "./note.md" --json

修改或追加笔记

lionote-cli update <noteId> --title "新的标题" --json
lionote-cli update <noteId> --content "新的正文" --json
lionote-cli update <noteId> --append --content "追加内容" --json

update 默认会替换传入的正文;需要保留原文时请使用 --append。同样可以通过 --file "./note.md" 或 --file - 传入较长内容。

笔记双链与反向引用

Lionote 使用 lionote://<noteId> 保存原生笔记引用。添加引用后,来源与目标的关联区域和关系图都能使用这项关联;目标会显示反向引用,无需在目标正文自动插入第二条链接。只有希望两篇正文互相引用时,才对调 ID 再添加一次。

先用 search、read 确认真实笔记 ID,写入前检查 doctor --json 的 writeSafe=true:

lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --text "相关资料" --json
lionote-cli link list --id <noteId> --json
lionote-cli link remove --id <sourceNoteId> --target <targetNoteId> --json

add 默认在来源正文添加 Markdown 引用,省略 --text 时使用目标标题;同一正文中已有该引用时不会重复插入。remove 默认仅删除来源正文中的目标引用;图节点或对方笔记仍引用时保留关联,返回 related=true,所有方向都无引用才清理双方关联。

link list 是只读查询,结果包含:

字段含义
outgoing当前笔记引用的笔记
incoming引用当前笔记的笔记,互相引用时同时出现在两组
locations每项引用的位置:area=body/mind/flow;图节点另有 nodeId
relationIds已保存的分号分隔关联集合,也由 read --json 返回;集合本身不表示方向

每条引用结果还包含目标笔记的 id、title。查询按当前账户的实际正文和图数据判断方向,也能发现历史遗漏登记的反链;失效或其他账户的目标不会列入有效结果。

思维导图和流程图节点引用

先查看真实节点 ID,再指定节点位置添加或移除引用:

lionote-cli diagram inspect --id <sourceNoteId> --nodes --json
lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --diagram mind --node <nodeId> --json
lionote-cli link remove --id <sourceNoteId> --target <targetNoteId> --diagram mind --node <nodeId> --json

mindMap.nodes 和 flowchart.nodes 返回节点的 id、text、link。思维导图使用 --diagram mind,流程图使用 --diagram flow;--diagram 与 --node 必须同时传入。操作只修改选中节点的引用,保留节点文字、位置和图内连线。一个节点只有一个引用,添加新目标会替换该节点原引用;其他节点和正文引用不变。

普通 create、update(含追加)和图形写入也自动维护双方关联。正文可写 [显示文字](lionote://<noteId>);直接写 [[标题]] 不会由 CLI 自动解析成笔记引用。只会为当前账户中有效的目标建立新关联,未同步或失效的链接文本仍保留。

兼容参数 --no-content-link 仅核对已有实际引用与关联:双方都无引用时 add 返回 LINK_REFERENCE_REQUIRED;remove 不会强制断开仍有实际引用的关系。图节点操作不接受这个参数。

这些扩展需要支持双链的新版 CLI(--version --json 的 protocolVersion 为 6 或更高);脚本可通过 capabilities --json 确认 lionote_list_note_links、lionote_add_note_link、lionote_remove_note_link。Windows 在 App 开启时由 App 执行并刷新,关闭时保持独立模式;正常写入后无需重启 App。

其他可用操作

CLI 还支持通过高层 JSON 生成思维导图和流程图,并维护标签、收藏和双链:

lionote-cli mind set --id <noteId> --data "<思维导图 JSON>" --json
lionote-cli flow set --id <noteId> --data "<流程图 JSON>" --json
lionote-cli tag add --id <noteId> --name "项目" --json
lionote-cli fav set --id <noteId> --json
lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --json

执行 lionote-cli --help 可以查看全部命令和参数。

AI Agent 调用规则

  1. 先执行 lionote-cli capabilities --json 了解能力,再执行 lionote-cli doctor --json。
  2. 只有 writeSafe=true 时才创建、追加或修改笔记;desktopRunning 仅作状态提示。
  3. 修改已有笔记前先执行 read <noteId> --json,确认目标和当前内容。
  4. 能追加时优先使用 update <noteId> --append;替换整篇正文前,应向用户明确说明这是覆盖式修改。
  5. 使用稳定命令名 lionote-cli,不要猜测安装目录或数据目录;自动定位失败时先检查 App 的账户和存储设置。macOS 商店版始终跟随 App 当前账户,不传目录或数据库覆盖参数。

CLI 负责实际执行命令。Skill 或 Agent 提示词只能帮助 AI 发现和正确调用 CLI,不能替代本机已安装且可访问的 CLI。

贡献者: Ray