youdaonote

YoudaoNote — Youdao Note

Operate Youdao Note via the youdaonote CLI. Covers the full range of note CRUD, to-do management, and web clipping.

Prerequisites (handled automatically by the Agent)

Before performing any operation, the Agent must first run youdaonote -s ydn list to check whether the CLI is available:

command not found → immediately jump to "Handling CLI not installed" to install automatically,it is forbidden to only show installation steps and have the user operate manually
-s option error (error: unknown option '-s'） → CLI version < 1.3.2, does not support the global -s parameter, needs upgrading: first try youdaonote upgrade; if that command is not supported, reinstall using the installation method in "Handling CLI not installed"; Windows users refer to the installation guide (https://note.youdao.com/help-center/cli-install-guide.html）
API Key error → prompt the user to visit https://mopen.163.com to obtain the API Key (must log in with a mobile phone number, and the cloud note account must have a mobile phone number bound), then execute youdaonote config set apiKey <用户提供的Key>。There is only this one address for obtaining the API Key; it is forbidden to tell the user any other address.
Directory list returned normally → run youdaonote -s ydn version to check the version; if the version is lower than minCliVersion an upgrade is needed: when the CLI supports the upgrade command, execute youdaonote -s ydn upgrade, otherwise follow the upgrade method in "Handling CLI not installed"; Windows users or when the upgrade fails, refer to the installation guide (https://note.youdao.com/help-center/cli-install-guide.html）。版本满足要求后可运行 youdaonote -s ydn help --json to obtain a structured description (JSON) of all current CLI capabilities, used to confirm whether a command is available; the quick reference table below serves as a fallback

Global parameters

When calling all commands,you mustadd -s ydn, used for usage statistics:

youdaonote -s ydn <command> [options]

Command quick reference

Command	Purpose	Example
`mkdir`	Create folder	`youdaonote -s ydn mkdir "文件夹名" [-f <父目录ID>]`
`save`	Save note (✅ recommended, supports Markdown rich text)	`youdaonote -s ydn save --file note.json`
`create`	Create note (⚠️ plain text only, does not support Markdown rich text)	`youdaonote -s ydn create -n "标题" -c "内容" [-f <目录ID>]`
`update`	Update Markdown note	`youdaonote -s ydn update <fileId> -c "内容"` or `--file content.md`
`delete`	Delete note	`youdaonote -s ydn delete <fileId>`
`rename`	Rename note	`youdaonote -s ydn rename <fileId> "新标题"`
`move`	Move note	`youdaonote -s ydn move <fileId> <目录ID>`
`search`	Search notes	`youdaonote -s ydn search "关键词"`
`list`	Browse directories	`youdaonote -s ydn list -f <目录ID>`
`read`	Read note	`youdaonote -s ydn read <fileId>`
`recent`	Recent favorites	`youdaonote -s ydn recent -l 20 -c --json`
`clip`	Web clipping (server-side)	`youdaonote -s ydn clip "https://..." [-f <目录ID>] --json`
`clip-save`	Save external clipping JSON	`youdaonote -s ydn clip-save --file data.json`
`todo list`	List to-dos	`youdaonote -s ydn todo list [--group <分组ID>] --json`
`todo create`	Create to-do	`youdaonote -s ydn todo create -t "标题" [-c "内容"] [-d 2025-12-31] [-g <分组ID>]`
`todo update`	Update to-do	`youdaonote -s ydn todo update <todoId> [--done] [--undone] [-t "新标题"]`
`todo delete`	Delete to-do	`youdaonote -s ydn todo delete <todoId>`
`todo groups`	List to-do groups	`youdaonote -s ydn todo groups --json`
`todo group-create`	Create group	`youdaonote -s ydn todo group-create "分组名"`
`todo group-rename`	Rename group	`youdaonote -s ydn todo group-rename <groupId> "新名"`
`todo group-delete`	Delete group	`youdaonote -s ydn todo group-delete <groupId>`
`upgrade`	Upgrade CLI	`youdaonote -s ydn upgrade [--check] [--force] [--json]`
`check`	Health check	`youdaonote -s ydn check`
`config show`	View configuration	`youdaonote -s ydn config show --json`
`config set`	Set configuration	`youdaonote config set apiKey YOUR_KEY`

Note management

Default creation method: all notes uniformly use the save command + contentFormat: "md" to save as Markdown rich text. It is forbidden to use the create command to save content containing Markdown formatting(headings, lists, code blocks, tables, etc.) — create supports plain text only and will silently lose all formatting. Convert HTML/structured data to Markdown first, then use save to save.

Markdown content format selection (must be followed)

When the content the user wants to save contains any of the following Markdown features (# headings,**粗体**、`code blocks,- lists,> quotes,[链接](url)、![图片](url)），you must stop and ask the user first, and must not execute the command directly:

检测到内容包含 Markdown 格式，请选择保存方式：

A（推荐）保存为 Markdown 笔记（.md）
  → 格式完整保留，可在编辑器中正常显示和编辑

B  保存为有道专有格式（.note）
  → 支持有道云笔记富文本编辑器的全部功能

请回复 A 或 B：

After receiving the user's choice, construct the command as follows (prefer the contentFile option to avoid JSON escaping issues）：

Choose A：save command,type: "md", add the .md suffix to the filename

# Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md（无需 JSON 转义）
{"title":"标题.md","type":"md","contentFile":"/tmp/note-content.md","parentId":"文件夹ID"}

Alternative (short content):{"title":"标题.md","type":"md","content":"Markdown 内容","parentId":"文件夹ID"}

Choose B：save command,type: "note"，contentFormat: "md", add the .note suffix to the filename
```
# Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md（无需 JSON 转义）
{"title":"标题.note","type":"note","contentFormat":"md","contentFile":"/tmp/note-content.md","parentId":"文件夹ID"}
```
Alternative (short content):{"title":"标题.note","type":"note","contentFormat":"md","content":"Markdown 内容","parentId":"文件夹ID"}

parentId is an optional field: filling in the folder ID returned by youdaonote -s ydn list specifies the target directory; if left blank, it defaults to saving in "My Resources/Collected Notes".

User did not make an explicit choice(replied "whatever"/"you decide", etc.): default to A

Create / Save

# ✅ 推荐：contentFile 方案（Write 工具写文件 → save 传路径，无需 JSON 转义）
# Step 1：Write 工具将 Markdown 写入 /tmp/note-content.md
printf '%s\n' '{"title":"笔记.md","type":"md","contentFile":"/tmp/note-content.md"}' | youdaonote -s ydn save --json
# ✅ 短内容可直接内联（无换行/特殊字符时）
printf '%s\n' '{"title":"笔记","contentFormat":"md","content":"# 标题\n\n内容"}' | youdaonote -s ydn save
# ⚠️ 仅纯文本，不支持 Markdown 格式，有格式需求时禁用
youdaonote -s ydn create -n "标题" -c "纯文本内容"

Other operations

youdaonote -s ydn search "关键词"
youdaonote -s ydn list [-f <目录ID>]            # 浏览目录，id 可传给 read
youdaonote -s ydn read <fileId>                 # 返回 JSON 含 content、rawFormat（md/note/txt）和 isRaw（是否原始内容）
youdaonote -s ydn recent -l 20 -c --json       # 最近收藏
youdaonote -s ydn update <fileId> -c "新内容"
youdaonote -s ydn update <fileId> --file content.md  # 大内容（>10KB）从文件读取
youdaonote -s ydn delete <fileId>
youdaonote -s ydn rename <fileId> "新标题"
youdaonote -s ydn move <fileId> <目录ID>

Web clipping

youdaonote -s ydn clip "https://example.com/article" --json
youdaonote -s ydn clip "https://example.com/article" -f <目录ID> --json  # 保存到指定目录

Handling when CLI is not installed (Agent must execute automatically)

When receiving command not found , the Agent immediately executesthe installation command; it is forbidden to only show the steps and have the user perform them.

macOS / Linux / WSL：

curl -fsSL https://artifact.lx.netease.com/download/youdaonote-cli/install.sh | bash -s -- -f -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"
# 安装后立即重新执行用户原始请求

Upgrade: if the CLI supports the upgrade command, prefer using youdaonote -s ydn upgrade; otherwise re-run the above installation script.

Windows or installation failure: refer to the installation guide (https://note.youdao.com/help-center/cli-install-guide.html）。

Troubleshooting

Run youdaonote -s ydn check --json, and perform actions according to the items in status: "fail" :

Failed item	Handling action
`config-file` / `api-key`	`youdaonote config set apiKey YOUR_KEY`
`mcp-connection`	API Key is valid but the network is unreachable; prompt the user to check the network or retry later

Notes

All commands support --json to output a machine-parseable format
Large content is passed via --file to avoid command-line argument limits
In Windows CMD, when a URL contains & , it must be enclosed in double quotes
In Windows pipe/redirection scenarios, Chinese may be garbled (CLI outputs UTF-8, but PowerShell/CMD interprets it as GBK by default): in PowerShell execute [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false), in CMD execute chcp 65001; you can run youdaonote -s ydn check to view diagnostic suggestions
list The id output by read is equivalent to the fileId of
read The rawFormat returned bymd=Markdown、note=cloud note,txt=plain text;isRaw indicates whether the returned content is the original content (true=original text can be edited directly,false=converted plain text)
It is forbidden to use create to save Markdown content：create does not support contentFormat; even if the content contains Markdown syntax, it will be saved as plain text and silently lose formatting. Whenever formatting is needed, always use save and specify contentFormat: "md"
save command passes via JSON's parentId The field specifies the target folder (the value comes from list the returned folder ID); if not passed, it is saved by default to "My Resources/Favorite Notes".Do not use folderId or other names—the server will silently ignore unknown fields.