From 564dedff4b04eef34b22127a60edc18caf6f86aa Mon Sep 17 00:00:00 2001 From: pablo-mano Date: Fri, 27 Feb 2026 20:36:51 +0100 Subject: [PATCH] Add README with installation guide for multiple agents Covers installation in Claude Code (Skills plugin), Cursor, Windsurf, GitHub Copilot, and any generic LLM agent. Includes prerequisites, quick examples, command overview table, and troubleshooting. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d776e8 --- /dev/null +++ b/README.md @@ -0,0 +1,167 @@ +# Obsidian CLI — Claude Code Skill + +A skill for AI coding agents that enables full control of [Obsidian](https://obsidian.md) vaults from the terminal using the official **Obsidian CLI** (v1.12+). + +![Obsidian](https://img.shields.io/badge/Obsidian-v1.12%2B-7C3AED?logo=obsidian&logoColor=white) +![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-D97757) + +--- + +## What This Skill Does + +Once installed, your AI agent will know how to interact with Obsidian vaults through the official CLI — reading, creating, and editing notes; managing daily notes; running full-text search; querying tasks, tags, links, and properties; managing plugins and sync; and running developer tools. + +Covers **100+ commands** across all major areas: + +| Area | Commands | +|---|---| +| **Files** | `read`, `create`, `append`, `prepend`, `move`, `delete`, `files`, `folders` | +| **Daily Notes** | `daily`, `daily:read`, `daily:append`, `daily:prepend` | +| **Search** | `search` with scoping, limits, JSON output | +| **Properties** | `properties`, `property:read`, `property:set`, `property:remove` | +| **Tags** | `tags`, `tag` with counts and filtering | +| **Tasks** | `tasks`, `task` — query, filter, toggle | +| **Links** | `backlinks`, `links`, `unresolved`, `orphans`, `deadends` | +| **Templates** | `templates`, `template:read`, `template:insert` | +| **Plugins** | `plugins`, `plugin:enable/disable/install/reload` | +| **Sync** | `sync`, `sync:status`, `sync:history`, `sync:restore` | +| **Developer** | `eval`, `dev:screenshot`, `dev:console`, `dev:errors` | +| **Vault** | `vault`, `vaults`, `version`, `recents`, `outline`, `wordcount` | + +--- + +## Prerequisites + +| Requirement | Details | +|---|---| +| **Obsidian Desktop** | v1.12.0+ (Insider / Early Access build) | +| **CLI enabled** | Settings → Command line interface → Toggle ON | +| **Obsidian running** | The desktop app must be running — the CLI communicates over IPC | +| **Catalyst License** | $25 one-time (Early Access); planned to be free for all users later | + +### Platform notes + +- **macOS / Linux** — the `obsidian` binary is added to PATH automatically when you enable CLI in settings. +- **Windows** — requires an `Obsidian.com` redirector file placed alongside `Obsidian.exe` (available in the `#insider-desktop-release` channel on Obsidian Discord). Must run from a **normal-privilege terminal** — admin terminals produce silent failures. +- **Headless Linux** — use the `.deb` package (not snap). Run under `xvfb` and prefix commands with `DISPLAY=:5`. Set `PrivateTmp=false` if running as a systemd service. + +--- + +## Installation + +### Claude Code — Skills Plugin (native) + +1. **Clone or download** this repository: + ```bash + git clone https://github.com/pablo-mano/Obsidian-CLI-skill.git + ``` +2. **Open Claude Code** and navigate to the **Skills plugin** settings. +3. **Import skill** — point to the cloned folder (or a `.zip` of it). +4. Done. The skill auto-triggers whenever you ask Claude to interact with Obsidian, automate vault operations, manage daily notes, search your vault, etc. + +> The skill uses Obsidian CLI syntax and patterns from `SKILL.md` and the full command reference in `references/command-reference.md`. + +--- + +### Cursor + +Cursor loads context via [Rules](https://docs.cursor.com/context/rules-for-ai). Add the skill as a project-level or global rule: + +1. Create the file `.cursor/rules/obsidian-cli.mdc` in your project root (or in `~/.cursor/rules/` for global scope). +2. Paste the body of `SKILL.md` (everything after the `---` frontmatter block) into the file. +3. Optionally append the contents of `references/command-reference.md` for the full command reference. + +Cursor will now apply Obsidian CLI knowledge when you work on related tasks. + +--- + +### Windsurf + +Windsurf uses [Rules](https://docs.windsurf.com/windsurf/memories-and-rules) stored in `.windsurf/rules/`: + +1. Create `.windsurf/rules/obsidian-cli.md` in your project. +2. Paste the body of `SKILL.md` (below the frontmatter) into the file. +3. Optionally include the command reference from `references/command-reference.md`. + +--- + +### GitHub Copilot (VS Code) + +Copilot supports [custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) via a repository-level file: + +1. Create `.github/copilot-instructions.md` in your repo. +2. Paste the body of `SKILL.md` into the file. + +For workspace-level instructions in VS Code, add the content to your VS Code settings under `"github.copilot.chat.codeGeneration.instructions"`. + +--- + +### Any Other LLM Agent or Assistant + +`SKILL.md` is a plain Markdown document. For any agent that supports custom system prompts or instructions: + +1. Open the agent's system prompt / custom instructions settings. +2. Paste the contents of `SKILL.md` (with or without the YAML frontmatter — most agents accept either). +3. Optionally include `references/command-reference.md` for the complete command reference. + +This works with Aider, Continue.dev, LM Studio, Open Interpreter, or any chat interface with a system prompt field. + +--- + +## Quick Examples + +### Append to today's daily note + +```bash +obsidian daily:append content="- [ ] Review pull requests" +``` + +### Search your vault and pipe to jq + +```bash +obsidian search query="meeting notes" format=json | jq '.[].path' +``` + +### Vault health check + +```bash +obsidian files total # Total file count +obsidian tags counts sort=count # Most-used tags +obsidian tasks # All open tasks +obsidian orphans # Notes with no links +obsidian unresolved # Broken wikilinks +``` + +### Create a note from a template with metadata + +```bash +obsidian create path="projects/new-feature" template="project-template" +obsidian property:set path="projects/new-feature.md" name="status" value="planning" +obsidian property:set path="projects/new-feature.md" name="created" value="$(date -I)" +obsidian daily:append content="- Started [[projects/new-feature|New Feature]]" +``` + +--- + +## Full Command Reference + +See [`references/command-reference.md`](references/command-reference.md) for the complete reference covering all commands, parameters, flags, output formatting, multi-vault usage, and headless Linux setup. + +--- + +## Troubleshooting + +| Problem | Cause | Fix | +|---|---|---| +| Empty output / hangs | Obsidian not running, or admin terminal (Windows) | Start Obsidian; use a normal-privilege terminal | +| `command not found` | CLI not registered in PATH | Re-enable CLI in Settings; restart terminal | +| Unicode errors | Bug fixed in v1.12.2+ | Update Obsidian | +| Wrong vault targeted | Multi-vault ambiguity | Pass vault name as the first argument: `obsidian "My Vault" ...` | +| IPC socket not found (Linux) | `PrivateTmp=true` in systemd unit | Set `PrivateTmp=false` | +| Snap confinement errors | Snap restricts IPC | Use the `.deb` package instead | + +--- + +## License + +This skill is provided as-is for use with the Obsidian CLI. Obsidian itself requires a [Catalyst license](https://obsidian.md/pricing) for Early Access builds.