Guide · Agent skill

How to use the SiYuan Note CLI agent skill (cli-anything-siyuan)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The cli-anything-siyuan skill gives an AI agent a set of commands for working with SiYuan (思源笔记), a local-first note-taking app. Once it is installed, the agent can list notebooks, create and edit documents and blocks, search your notes and export them to Markdown. This guide is for SiYuan users who want an agent to work with their local knowledge base, and it walks through what an agent skill is, how to install this one, how to trigger it and how to use it safely.

SiYuan Note CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill

Quick start

1Install SiYuan and get the API token. Open SiYuan on your computer and copy the API token from Settings → About.
2Install the CLI. Run pip install cli-anything-siyuan with Python 3.10 or newer, or use pip install -e . from the agent-harness folder.
3Save the token. Store the token in ~/.siyuan-cli.json or set the SIYUAN_TOKEN environment variable.
4Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
5Check the connection. Run cli-anything-siyuan status to confirm the CLI reaches your running SiYuan kernel.
6Ask the agent in plain language. Make a request about your notes, such as listing notebooks or searching for a keyword, and review any delete or write action before it runs.

What is an agent skill and what does this one let the agent do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to use a tool. This skill is built around a command-line tool called cli-anything-siyuan. The SKILL.md describes its command groups so the agent knows which commands exist and how to call them.

The tool connects to a SiYuan kernel that is already running on your computer through its HTTP API at http://127.0.0.1:6806. Through it the agent can manage notebooks, documents and blocks, run full-text and SQL searches, export documents to Markdown, list tags and check connection status.

Notebooks: list, create, rename, open and remove
Documents: create, list, show as a tree, get path by ID, rename and remove
Blocks: insert, update, delete, get kramdown source and list children
Search: full-text search across blocks and SQL queries on the block database
Export: export a document as Markdown; list tags; show kernel version and connection status

Install the cli-anything-siyuan skill

Download the skill ZIP from this page and unzip it. For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps, upload the skill under Settings → Capabilities → Skills instead.

The skill itself only tells the agent how to use the CLI, so you also need the CLI installed. The SKILL.md lists two options: install from PyPI, or install in editable mode from the agent-harness folder of the source.

pip install cli-anything-siyuan
# or, from the agent-harness/ folder:
pip install -e .

Check the requirements before you start

You need the SiYuan desktop app running on the same computer, Python 3.10 or newer, and the SiYuan API token. The token is shown in SiYuan under Settings → About. The CLI reads it from ~/.siyuan-cli.json or from the SIYUAN_TOKEN environment variable.

The tool only reaches a SiYuan kernel at 127.0.0.1:6806 by default, so it will not work with other note apps.

SiYuan desktop app running locally
API token from Settings → About, stored in ~/.siyuan-cli.json or SIYUAN_TOKEN
Python 3.10+
cli-anything-siyuan installed with pip

Trigger the skill with natural requests

You do not need to type commands yourself. Once the skill is installed and SiYuan is running, ask the agent in plain language about your SiYuan notes. The agent will choose the matching command from the skill's command groups.

Be specific about the notebook, document or topic. Document IDs look like 20210817205410-2kvfpfn, so you can also give the agent an ID if you have one.

"List my SiYuan notebooks."
"Search my SiYuan notes for anything mentioning the Q3 budget."
"Create a document called /projects/new in my notebook nb1 with a short summary of today's meeting."
"Export document 20210817205410-2kvfpfn to Markdown."
"Check whether the CLI can connect to SiYuan."

Example commands the agent may run

These are the commands from the source. You can run them yourself to test the setup. The skill recommends --json for machine-readable output. Writing Markdown on the command line needs care with shell escaping, so the source suggests piping content through stdin with --md -.

Use --json for output the agent can parse.
Pipe multi-line Markdown through stdin to avoid escaping problems with backticks, parentheses and quotes.

cli-anything-siyuan --json notebook list

cli-anything-siyuan sql "SELECT id, content FROM blocks WHERE content LIKE '%meeting%' LIMIT 5"

cli-anything-siyuan export md doc123

cat <<'EOF' | cli-anything-siyuan doc create nb1 /projects/new --md -
## Title
Content with `backticks` and (parentheses)
EOF

Safety: scripts, network and destructive commands

This skill runs scripts and uses the network. The network use is to your own SiYuan app on 127.0.0.1:6806, not to remote services as far as the source describes. Your API token gives access to your notes, so keep it private.

Some commands permanently delete content: notebook remove, doc remove and block delete. The sql command can run arbitrary statements that modify the database. Back up your SiYuan data before letting an agent run bulk edits or deletions, and review commands that remove or change content.

Back up your notes before bulk or destructive operations
Review any delete command the agent proposes
Treat the API token like a password
Keep SiYuan running locally; the CLI does not target other apps

Troubleshooting connection and token errors

If a command fails, check the error. The source says connection errors usually mean SiYuan is not running or the token is wrong. API errors come back as a code and a msg field, so read the msg value. Auth errors mean the token in ~/.siyuan-cli.json or the SIYUAN_TOKEN variable is incorrect.

You can ask the agent to run the status command, which shows connection and session status, to confirm the setup.

Connection error: confirm SiYuan is open and the API token is correct
API error: read the msg field in the returned code and msg
Auth error: check ~/.siyuan-cli.json or SIYUAN_TOKEN

cli-anything-siyuan status

What people use it for

Search your notebooks for a keyword or phrase across all blocks
Create a new document from a Markdown summary of a meeting or draft
Export one or more documents to Markdown for sharing or backup
Run bulk edits or scripted updates to blocks with the CLI, after taking a backup
Explore notebook structure with the document tree and tag list

Frequently asked questions

Is the cli-anything-siyuan skill free?

The skill is licensed under Apache-2.0, as listed for this item. Check the license file in the source repository for the full terms.

What do I need to use the SiYuan CLI skill?

You need the SiYuan desktop app running locally, its API token from Settings → About, Python 3.10 or newer, and the cli-anything-siyuan package installed with pip. The default address is http://127.0.0.1:6806.

Where do I put the skill files for Claude?

Unzip the downloaded skill into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

Can this skill work with Obsidian or other note apps?

No. The tool only reaches a SiYuan kernel at 127.0.0.1:6806 by default, so it is designed for SiYuan alone.

Why does the CLI say a connection failed or the token is wrong?

The usual causes are that SiYuan is not running, or the API token in ~/.siyuan-cli.json or SIYUAN_TOKEN does not match the one in Settings → About. Run cli-anything-siyuan status to check the connection.

Can the agent delete my notes by mistake?

It can run commands that delete content, such as notebook remove, doc remove and block delete, and sql can modify the database. Back up your SiYuan data first and review any delete or write command before it runs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits SiYuan users who want an agent to search, organise or write into a local knowledge base, and developers who script bulk edits or exports. It is less suitable if you use other note apps, do not run SiYuan on your own machine, or are not comfortable reviewing terminal commands that can delete content. If you want an agent to work with a different note tool, pick a skill built for that app.

Download the skill