Guide · Agent skill
How to use the Obsidian Vault CLI agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the cli-anything-obsidian agent skill, which teaches an AI agent to manage an Obsidian vault (a folder of Markdown notes) through a command-line tool. It is written for people who have never used agent skills before. By the end you will know what the skill lets the agent do, how to install it, how to ask for things in plain language, and which safety points to check first.
Obsidian Vault CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill Quick start
- 1Install the Python package. Run pip install cli-anything-obsidian on a machine with Python 3.10 or newer.
- 2Enable the Local REST API plugin. In Obsidian, make sure the Local REST API community plugin is installed, enabled and the app is running.
- 3Install the skill folder. Download the ZIP from this page, unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Set your API key. Export OBSIDIAN_API_KEY with your Local REST API key so the CLI can authenticate.
- 5Check the connection. Run cli-anything-obsidian server status to confirm Obsidian and the plugin are reachable.
- 6Ask in plain language. Request a note action, such as listing a folder or reading a note, and the agent will use the matching commands.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file that tells an AI agent how to use a particular tool. This skill teaches the agent to use a command-line tool called cli-anything-obsidian to work with an Obsidian knowledge base.
Once installed, the agent can list, read, create, overwrite, append to and delete notes. It can also run plain-text or query-based searches, check or open the active note, and run Obsidian command-palette actions by ID. The tool works without the Obsidian window by talking to the Obsidian Local REST API plugin.
- List, read, create, update (overwrite), append and delete notes
- Plain text search and query-based search
- Get or open the active note
- List and execute Obsidian commands by ID
- Structured JSON output for agent use
What you need before installing
The skill needs Python 3.10 or newer and the Obsidian desktop app running. You also need the Local REST API community plugin enabled in Obsidian, plus its API key. The CLI cannot work without the plugin.
- Python 3.10+
- Obsidian desktop app installed and running
- Obsidian Local REST API community plugin enabled
- Local REST API key, supplied as OBSIDIAN_API_KEY or the --api-key flag
- pip package cli-anything-obsidian
pip install cli-anything-obsidianHow do you install the skill?
Download the ZIP from this page and unzip it. Then place the resulting skill folder in one of two locations: ~/.claude/skills/ to make it available everywhere, or a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.
Separately, install the command-line package with pip as shown above, since the skill calls the cli-anything-obsidian tool.
- Option A: unzip into ~/.claude/skills/ for all projects
- Option B: unzip into a project's .claude/skills/ folder
- Option C: upload in the Claude apps under Settings → Capabilities → Skills
How do you set the API key and check the connection?
The recommended approach for agents is to set the OBSIDIAN_API_KEY environment variable so you do not pass the key on every call. The default host is https://localhost:27124, which you can change with --host.
Before anything else, the agent should run the server status check to confirm Obsidian and the plugin are reachable.
- Set the key once with an environment variable
- Use --api-key only for one-off commands
- Use --host if your Local REST API runs somewhere other than the default
export OBSIDIAN_API_KEY=YOUR_KEY
cli-anything-obsidian server status
cli-anything-obsidian vault listHow do you trigger the skill with natural requests?
You do not need to type commands yourself. Ask the agent in plain language, mentioning your notes or vault, and it should choose the matching commands. Examples of requests that fit the skill include listing notes in a folder, reading a named note, creating a new note with some content, appending a section to an existing note, or searching the vault for a phrase.
If you want to see the commands directly, you can run them yourself. The tool has a help flag, an interactive REPL mode, and a --json flag for machine-readable output.
- "List the notes in my Daily Notes folder."
- "Read Projects/my-project.md and summarise it."
- "Search my vault for meeting notes."
- "Add a new section called Next steps to Projects/new-project.md."
- "What note am I looking at in Obsidian right now?"
cli-anything-obsidian --help
cli-anything-obsidian --json vault listWhat are the main commands and examples?
Commands are grouped into vault, search, note, command, server and session. Vault commands manage files, search commands find text or run queries, and note commands handle the active note. Searches can use Dataview DQL (the default) or JsonLogic queries.
The examples below show reading a note, creating and appending to one, and running a Dataview query and a command palette action.
- vault: list, read, create, update, delete, append
- search: simple, query (with --type jsonlogic for JsonLogic)
- note: active, open
- command: list, execute
- server: status
- session: status
cli-anything-obsidian vault read "Projects/my-project.md"
cli-anything-obsidian vault append "Projects/new-project.md" --content "\n## New Section"
cli-anything-obsidian search query 'TABLE file.link FROM "Projects"'
cli-anything-obsidian command execute "editor:toggle-bold"What safety points should you check?
The skill runs scripts and uses the network. The CLI talks to your local Obsidian instance over the Local REST API. The API key grants broad read and write access to all notes in the vault, so treat it as sensitive.
The delete and update commands can destroy content without a backup. Before letting an agent use them on important notes, make a backup of your vault. Do not use this skill on sensitive vaults with agents you do not trust.
- Keep a backup of your vault before allowing delete or overwrite commands
- Treat OBSIDIAN_API_KEY as a secret with full read and write access
- Use only with agents you trust, especially on sensitive vaults
- The agent should check return codes and parse stderr on failure, per the skill's guidance
What people use it for
- Listing and reading notes in a project or daily notes folder for an agent to summarise
- Running plain text or Dataview queries to find notes by topic or status
- Appending a new section to a running log note
- Checking which note is active in Obsidian before working on it
- Running a command palette action such as toggling bold in the editor by its ID
Frequently asked questions
How do I install the Obsidian CLI agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects or a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills. Separately, install the command-line tool with pip install cli-anything-obsidian.
What do I need to run cli-anything-obsidian?
You need Python 3.10 or newer, the Obsidian desktop app running, the Obsidian Local REST API community plugin enabled, and your Local REST API key. The key can be supplied as OBSIDIAN_API_KEY or with the --api-key flag.
Is this skill free to use?
The source does not state pricing or licence terms in the skill file itself. This page lists the item's licence as Apache-2.0. Check the licence in the project repository before using it in your own work.
Why does the CLI say it cannot connect?
The CLI needs Obsidian running with the Local REST API plugin enabled. Run cli-anything-obsidian server status to check. The default host is https://localhost:27124, so use --host if your setup differs.
Can the agent delete or overwrite my notes?
Yes. The vault commands include delete and update, and update overwrites an existing note. Keep a backup of your vault before you allow these actions, especially on important notes.
How is this different from using Obsidian directly?
This skill lets an agent manage notes without the Obsidian window, through the Local REST API plugin. It also provides JSON output for agent workflows, which the normal interface does not focus on.
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 power users and developers who want an AI agent to organise, search or automate notes in an Obsidian vault and can run the Local REST API plugin. It is a poor fit if you do not want an agent able to delete or overwrite notes, or if you plan to use sensitive vaults with agents you do not fully trust, since the API key grants broad access.
Download the skill