YoudaoNote — Youdao Cloud Note

Operate Youdao Cloud Note via the

youdaonote

CLI. Covers full scenarios including note CRUD, to-do management, and web clipping.

Prerequisites (Automatically handled by Agent)

Before performing any operation, the Agent must first run

youdaonote list

to check if the CLI is available:

command not found
→ Immediately jump to "CLI Not Installed Handling" for automatic installation. Do NOT only display installation steps and let users operate manually
API Key error → Prompt users to visit https://mopen.163.com to obtain an API Key (must log in with a mobile phone number, and the cloud note account must be bound to a mobile phone number), then execute
```
youdaonote config set apiKey <User-provided Key>
```
. This is the only address for obtaining the API Key; do NOT inform users of other addresses.
Directory list returned normally → Run
```
youdaonote version
```
to check the version. If the version is lower than
```
minCliVersion
```
, upgrade is required: if the CLI supports the
```
upgrade
```
command, execute
```
youdaonote upgrade
```
; otherwise, follow the upgrade method in "CLI Not Installed Handling". For Windows users or if upgrade fails, refer to the installation guide (https://note.youdao.com/help-center/cli-install-guide.html). After the version meets the requirements, run
```
youdaonote help --json
```
to get a structured description (JSON) of all current CLI capabilities, which is used to confirm whether the command is available. The quick reference table below serves as a fallback

Command Quick Reference

Command	Purpose	Example
`mkdir`	Create folder	`youdaonote mkdir "Folder Name" [-f <Parent Directory ID>]`
`save`	Save note (✅ Recommended, supports Markdown rich text)	`youdaonote save --file note.json`
`create`	Create note (⚠️ Plain text only, does not support Markdown rich text)	`youdaonote create -n "Title" -c "Content" [-f <Directory ID>]`
`update`	Update Markdown note	`youdaonote update <fileId> -c "Content"` or `--file content.md`
`delete`	Delete note	`youdaonote delete <fileId>`
`rename`	Rename note	`youdaonote rename <fileId> "New Title"`
`move`	Move note	`youdaonote move <fileId> <Directory ID>`
`search`	Search notes	`youdaonote search "Keyword"`
`list`	Browse directory	`youdaonote list -f <Directory ID>`
`read`	Read note	`youdaonote read <fileId>`
`recent`	Recent favorites	`youdaonote recent -l 20 -c --json`
`clip`	Web clipping (server-side)	`youdaonote clip "https://..." [-f <Directory ID>] --json`
`clip-save`	Save external clipping JSON	`youdaonote clip-save --file data.json`
`todo list`	List to-dos	`youdaonote todo list [--group <Group ID>] --json`
`todo create`	Create to-do	`youdaonote todo create -t "Title" [-c "Content"] [-d 2025-12-31] [-g <Group ID>]`
`todo update`	Update to-do	`youdaonote todo update <todoId> [--done] [--undone] [-t "New Title"]`
`todo delete`	Delete to-do	`youdaonote todo delete <todoId>`
`todo groups`	List to-do groups	`youdaonote todo groups --json`
`todo group-create`	Create group	`youdaonote todo group-create "Group Name"`
`todo group-rename`	Rename group	`youdaonote todo group-rename <groupId> "New Name"`
`todo group-delete`	Delete group	`youdaonote todo group-delete <groupId>`
`upgrade`	Upgrade CLI	`youdaonote upgrade [--check] [--force] [--json]`
`check`	Health check	`youdaonote check`
`config show`	View configuration	`youdaonote config show --json`
`config set`	Set configuration	`youdaonote config set apiKey YOUR_KEY`

Note Management

Default creation method: All notes must be saved as Markdown rich text using the

save

command +

contentFormat: "md"

. Do NOT use the
create
command to save content containing Markdown formatting (titles, lists, code blocks, tables, etc.) —

create

only supports plain text and will silently lose all formatting. Convert HTML/structured data to Markdown first, then save with

save

Markdown Content Format Selection (Must Follow)

When the content to be saved by the user contains any of the following Markdown features (

title,

**bold**

code block,

list,

quote,

[link](url)

![image](url)

), must stop and ask the user first, do not execute the command directly:

Detected Markdown formatting in content, please select the save method:

A (Recommended) Save as Markdown note (.md)
  → Format is fully preserved, can be displayed and edited normally in the editor

B  Save as Youdao proprietary format (.note)
  → Supports all features of Youdao Cloud Note rich text editor

Please reply with A or B:

After receiving the user's selection, construct the command as follows (Prioritize the
contentFile
solution to avoid JSON escaping issues):

Option A:

save

command,

type: "md"

, add

.md

suffix to the file name

# Step 1: Write tool writes Markdown to /tmp/note-content.md (no JSON escaping needed)
{"title":"Title.md","type":"md","contentFile":"/tmp/note-content.md","parentId":"Folder ID"}

Alternative (short content):

{"title":"Title.md","type":"md","content":"Markdown Content","parentId":"Folder ID"}

Option B:

save

command,

type: "note"

contentFormat: "md"

, add

.note

suffix to the file name

# Step 1: Write tool writes Markdown to /tmp/note-content.md (no JSON escaping needed)
{"title":"Title.note","type":"note","contentFormat":"md","contentFile":"/tmp/note-content.md","parentId":"Folder ID"}

Alternative (short content):

{"title":"Title.note","type":"note","contentFormat":"md","content":"Markdown Content","parentId":"Folder ID"}

parentId
is an optional field: Fill in the folder ID returned by
youdaonote list
to specify the target directory; if not filled, it will be stored in "My Resources/Favorite Notes" by default.

User does not explicitly select (replies "whatever"/"you decide", etc.): Default to Option A

Create / Save

bash

# ✅ Recommended: contentFile solution (Write tool writes file → save passes path, no JSON escaping needed)
# Step 1: Write tool writes Markdown to /tmp/note-content.md
printf '%s\n' '{"title":"Note.md","type":"md","contentFile":"/tmp/note-content.md"}' | youdaonote save --json
# ✅ Short content can be directly inline (when no line breaks/special characters)
printf '%s\n' '{"title":"Note","contentFormat":"md","content":"# Title\n\nContent"}' | youdaonote save
# ⚠️ Plain text only, does not support Markdown formatting, disable when formatting is required
youdaonote create -n "Title" -c "Plain Text Content"

Other Operations

bash

youdaonote search "Keyword"
youdaonote list [-f <Directory ID>]            # Browse directory, id can be passed to read
youdaonote read <fileId>                 # Returns JSON containing content, rawFormat (md/note/txt) and isRaw (whether the content is original)
youdaonote recent -l 20 -c --json       # Recent favorites
youdaonote update <fileId> -c "New Content"
youdaonote update <fileId> --file content.md  # Large content (>10KB) read from file
youdaonote delete <fileId>
youdaonote rename <fileId> "New Title"
youdaonote move <fileId> <Directory ID>

Web Clipping

bash

youdaonote clip "https://example.com/article" --json
youdaonote clip "https://example.com/article" -f <Directory ID> --json  # Save to specified directory

CLI Not Installed Handling (Agent Must Execute Automatically)

When receiving

command not found

, the Agent must execute the installation command immediately, do NOT only display steps and let users operate manually.

macOS / Linux / WSL:

bash

curl -fsSL https://artifact.lx.netease.com/download/youdaonote-cli/install.sh | bash -s -- -f -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"
# Re-execute the user's original request immediately after installation

Upgrade: If the CLI supports the

upgrade

command, prioritize using

youdaonote upgrade

; otherwise, re-execute 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 check --json

, and perform actions based on items with

status: "fail"

Failed Item	Action
`config-file` / `api-key`	`youdaonote config set apiKey YOUR_KEY`
`mcp-connection`	API Key is valid but network is unreachable, prompt user to check network or try again later

Notes

All commands support
```
--json
```
output for machine-readable format
Pass large content via
```
--file
```
to avoid command line parameter limits
URLs containing
```
&
```
in Windows CMD must be enclosed in double quotes
Chinese characters may be garbled in Windows pipe/redirection scenarios (CLI outputs UTF-8, but PowerShell/CMD defaults to GBK interpretation): Execute
```
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
```
in PowerShell, or
```
chcp 65001
```
in CMD; run
```
youdaonote check
```
to view diagnostic suggestions
```
id
```
output by
```
list
```
is equivalent to
```
fileId
```
for
```
read
```
```
rawFormat
```
returned by
```
read
```
identifies the original note format:
```
md
```
=Markdown,
```
note
```
=Cloud Note,
```
txt
```
=Plain Text;
```
isRaw
```
identifies whether the returned content is original (
```
true
```
=original text can be edited directly,
```
false
```
=converted plain text)
Do NOT 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 with formatting silently lost. For formatting needs, always use
```
save
```
and specify
```
contentFormat: "md"
```
The
```
save
```
command specifies the target folder via the parentId
field in JSON (value comes from the folder ID returned by
```
list
```
); if not passed, it will be saved to "My Resources/Favorite Notes" by default. Do NOT use other names such as
folderId
— the server will silently ignore unknown fields.

youdaonote

NPX Install

Tags

SKILL.md Content (Chinese)

YoudaoNote — Youdao Cloud Note

Prerequisites (Automatically handled by Agent)

Command Quick Reference

Note Management

Markdown Content Format Selection (Must Follow)

Create / Save

Other Operations

Web Clipping

CLI Not Installed Handling (Agent Must Execute Automatically)

Troubleshooting

Notes