How to use the Joplin Notes CLI Harness agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file. The file tells an AI agent when to use a capability and how to run it. This skill is defined by a SKILL.md file that describes a stateful harness backed by the real joplin terminal binary.

Once the skill is active, the agent can automate Joplin notebook, note, to-do, tag, attachment, search, sync, and import/export workflows through that command-line tool.

• Manage notebooks: list, create, use, remove
• Manage notes: list, create, set, get, remove, copy, move, rename
• Manage to-dos: list, create, toggle, clear, done, undone
• Manage tags and attachments, run search, sync, and import or export notes
• Save multi-step work to a project file so the history is persisted

Install the cli-anything-joplin skill

Download the skill ZIP from this page and unzip it into one of these locations: ~/.claude/skills/ for a personal install, or a project's .claude/skills/ folder for a single project. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill's own install step is for the command-line package. Before the agent can run anything, the Joplin terminal app must be installed and available as joplin on your PATH. Then, from the joplin/agent-harness folder in the repository, install the package in editable mode.

• Python 3.10 or newer
• Joplin terminal binary available as joplin on PATH
• Optional: pass --profile to target a specific Joplin profile

Try the command line before you hand it to the agent

The skill runs the cli-anything-joplin command. Running it yourself first shows you what the agent will see. With no arguments it starts REPL mode. For machine-readable output, add --json to a one-shot command.

For repeatable work, create a project file. Commands that change data auto-save the project unless you use --dry-run, which lets you preview a change without saving it.

Trigger the skill with natural requests

You do not need to type commands yourself. Ask the agent in plain language and name Joplin so it picks up this skill. Be specific about the notebook, the notes and the outcome you want, and say whether you want a preview first.

Good requests name the scope and the action. For example: list the notes in a notebook, tag a set of notes, or export a notebook. For anything that changes data, ask the agent to dry-run first so you can read the result.

• "Using Joplin, list the notes in my Work notebook as JSON."
• "In Joplin, add the tag 'review' to every note in the Meeting notebook. Dry-run first and show me what would change."
• "Create a Joplin project file for this week's cleanup and record each step in it."
• "Sync my Joplin notes and tell me if any command failed."

Understand the JSON output

When --json is on, every command returns the same shape, which makes results easy for the agent or a script to check. Each response contains an ok flag, a stable command name such as notes.list or todos.toggle, a data payload, and an error field that is null on success.

• ok: true or false
• command: stable identifier such as notes.list or todos.toggle
• data: the command's payload
• error: null on success, or an object with type and message on failure

Safety notes before you let it run

This skill runs scripts and uses the network. Commands can change or delete notes, and sync may upload data. Only use it on notes that you are comfortable exposing to an automated tool. Use --dry-run for changes and keep a copy of important notes first.

Backend stdout and stderr are returned verbatim, so warnings are not stripped from note bodies or exports. Check exported output before you share it.

• Use --dry-run before mutating commands
• Do not run it on notes that must stay private from automated tools
• Sync and import/export can move data outside your machine; confirm the target first

Tips and known limits

Search may not always work. Some Joplin CLI builds only allow search in GUI mode. If the output says "only available in GUI mode", treat search as best-effort rather than relying on it.

In REPL mode, changes are not auto-saved, so run project save explicitly. Joplin 3.6.x can have a broken version command in npm global layouts; the harness then falls back to installed package metadata for backend version.

• Prefer --json so results are parseable
• Use --project for multi-step work so history is kept
• Run project save after changes made in REPL mode
• Multi-word subcommands use a dot, such as config.import_file