Fix Cursor installation docs: replace outdated Rules-based GitHub install with correct terminal commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "obsidian-cli-skill",
+  "description": "Obsidian CLI skill for Claude Code — interact with Obsidian vaults from the terminal",
+  "owner": {
+    "name": "pablo-mano"
+  },
+  "plugins": [
+    {
+      "name": "obsidian-cli",
+      "description": "Interact with Obsidian vaults using the official Obsidian CLI (v1.12+). Read, create, append, search, and manage notes, daily notes, properties, tags, tasks, bookmarks, templates, themes, sync, plugins, and links — all from the terminal.",
+      "author": {
+        "name": "pablo-mano"
+      },
+      "source": "./plugins/obsidian-cli",
+      "category": "productivity",
+      "homepage": "https://github.com/pablo-mano/Obsidian-CLI-skill"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "obsidian-cli",
   "description": "Interact with Obsidian vaults using the official Obsidian CLI (v1.12+). Read, create, append, search, and manage notes, daily notes, properties, tags, tasks, bookmarks, templates, themes, sync, plugins, and links — all from the terminal.",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "author": {
     "name": "pablo-mano"
   },

README.md

@@ -53,6 +53,17 @@ Covers **100+ commands** across all major areas:
 
 ### Claude Code — Plugin (native)
 
+**Option A — Marketplace install (recommended):**
+
+```
+/plugin marketplace add https://github.com/pablo-mano/Obsidian-CLI-skill
+/plugin install obsidian-cli
+```
+
+Done — the skill auto-triggers when you ask Claude to interact with Obsidian.
+
+**Option B — Direct plugin load:**
+
 1. Clone this repository:
    ```bash
    git clone https://github.com/pablo-mano/Obsidian-CLI-skill
@@ -61,9 +72,10 @@ Covers **100+ commands** across all major areas:
    ```bash
    claude --plugin-dir ./Obsidian-CLI-skill
    ```
-3. Done — the skill auto-triggers when you ask Claude to interact with Obsidian, automate vault operations, manage daily notes, search your vault, etc.
 
-**Persistent setup** — add to your project's `.claude/settings.json` so the plugin loads automatically:
+**Option C — Persistent via `settings.json`:**
+
+Add to your project's `.claude/settings.json`:
 ```json
 {
   "plugins": {
@@ -74,7 +86,7 @@ Covers **100+ commands** across all major areas:
 }
 ```
 
-> The `.claude-plugin/plugin.json` manifest makes this repository directly compatible with Claude Code's plugin system.
+> The `.claude-plugin/marketplace.json` manifest makes this repository compatible with Claude Code's marketplace system.
 
 ---
 
@@ -82,17 +94,30 @@ Covers **100+ commands** across all major areas:
 
 Cursor has a native skills system (launched Feb 2026) that is directly compatible with the `SKILL.md` format — no rules file needed.
 
-**Option A — GitHub install (recommended):**
+In a terminal:
-1. Open Cursor Settings → Rules
-2. Click **Add Rule** → **Remote Rule (GitHub)**
-3. Paste `https://github.com/pablo-mano/Obsidian-CLI-skill`
-4. Done — the skill auto-triggers on Obsidian-related tasks.
 
-**Option B — Local copy:**
+```bash
-1. Clone or download this repo
+git clone --depth 1 https://github.com/pablo-mano/Obsidian-CLI-skill /tmp/Obsidian-CLI-skill
-2. Copy the folder into your project: `.cursor/skills/obsidian-cli/`
+mkdir -p ~/.cursor/skills
-   (or globally: `~/.cursor/skills/obsidian-cli/`)
+cp -r /tmp/Obsidian-CLI-skill/skills/obsidian-cli ~/.cursor/skills/obsidian-cli
-3. Cursor picks it up automatically — no restart needed.
+rm -rf /tmp/Obsidian-CLI-skill
+```
+
+Cursor picks it up automatically — no restart needed.
+
+---
+
+### GitHub Copilot (VS Code)
+
+Copilot supports [custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) via repository files:
+
+**Option A — Repository-wide (recommended):**
+1. Create `.github/copilot-instructions.md` in your repo.
+2. Paste the body of `SKILL.md` into the file.
+
+**Option B — Path-scoped:**
+1. Create `.github/instructions/obsidian-cli.instructions.md`
+2. Add frontmatter `applyTo: "**/*"` then paste the `SKILL.md` body.
 
 ---
 
@@ -135,20 +160,6 @@ Openclaw loads skills from the `skills/` directory at the project root using the
 
 ---
 
-### GitHub Copilot (VS Code)
-
-Copilot supports [custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) via repository files:
-
-**Repository-wide** (applies to all files):
-1. Create `.github/copilot-instructions.md` in your repo.
-2. Paste the body of `SKILL.md` into the file.
-
-**Path-scoped** (optional alternative):
-1. Create `.github/instructions/obsidian-cli.instructions.md`
-2. Add frontmatter `applyTo: "**/*"` then paste the `SKILL.md` body.
-
----
-
 ### Any Other LLM Agent or Assistant
 
 `SKILL.md` is a plain Markdown document. For any agent that supports custom system prompts or instructions:

plugins/obsidian-cli/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "obsidian-cli",
+  "description": "Interact with Obsidian vaults using the official Obsidian CLI (v1.12+). Read, create, append, search, and manage notes, daily notes, properties, tags, tasks, bookmarks, templates, themes, sync, plugins, and links — all from the terminal.",
+  "version": "1.0.4",
+  "author": {
+    "name": "pablo-mano"
+  },
+  "homepage": "https://github.com/pablo-mano/Obsidian-CLI-skill",
+  "repository": "https://github.com/pablo-mano/Obsidian-CLI-skill"
+}

plugins/obsidian-cli/skills/obsidian-cli/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: obsidian-cli
+description: >
+  Interact with Obsidian vaults using the official Obsidian CLI (v1.12+).
+  Read, create, append, search, and manage notes, daily notes, properties, tags,
+  tasks, bookmarks, templates, themes, sync, plugins, and links — all from the terminal.
+  Use this skill whenever the user mentions Obsidian CLI, wants to automate Obsidian
+  vault operations, manage notes programmatically, script daily note workflows,
+  query vault metadata, or integrate Obsidian with AI agents or automation pipelines.
+  Also trigger when the user asks about controlling Obsidian from the command line,
+  building scripts around their knowledge base, or running headless Obsidian setups.
+  Even if the user just says "add something to my daily note" or "search my vault"
+  in a CLI/scripting context, this skill applies.
+---
+
+# Obsidian CLI
+
+The official Obsidian CLI (released in v1.12, February 2026) lets you control every aspect of Obsidian from the terminal. It communicates with a running Obsidian desktop instance via IPC.
+
+> For the full command reference with all subcommands, flags and examples, read
+> `references/command-reference.md` in this skill folder.
+
+## Prerequisites
+
+| Requirement | Details |
+|---|---|
+| Obsidian Desktop | **v1.12.0+** |
+| CLI enabled | Settings → Command line interface → Toggle ON |
+| Obsidian running | The desktop app **must be running** for CLI to work (IPC) |
+
+### Platform Notes
+
+- **macOS / Linux**: The `obsidian` binary is registered in PATH automatically when you enable CLI in settings.
+- **Windows**: Requires an `Obsidian.com` redirector file placed alongside `Obsidian.exe`. **Must run with normal user privileges** — admin terminals produce silent failures.
+- **Headless Linux**: Use the `.deb` package (not snap). Run under `xvfb`. Prefix commands with `DISPLAY=:5` (or your xvfb display number). Ensure `PrivateTmp=false` if running as a service.
+
+## Syntax
+
+All parameters use **`key=value`** syntax. Quote values containing spaces.
+
+```bash
+obsidian <command> [subcommand] [key=value ...] [flags]
+```
+
+### Multi-Vault
+
+Target a specific vault by making it the **first argument**:
+
+```bash
+obsidian "My Vault" daily:read
+obsidian "Work Notes" search query="meeting"
+```
+
+If omitted, the CLI targets the most recently active vault.
+
+## Command Overview
+
+The CLI provides **100+ commands** across these groups:
+
+| Group | Key Commands | Purpose |
+|---|---|---|
+| **files** | `read`, `create`, `append`, `prepend`, `move`, `delete`, `files`, `folders`, `file` | Note CRUD and file discovery |
+| **daily** | `daily`, `daily:read`, `daily:append`, `daily:prepend` | Daily note operations |
+| **search** | `search` | Full-text vault search with scoping and JSON output |
+| **properties** | `properties`, `property:read`, `property:set`, `property:remove`, `aliases` | Frontmatter/metadata management |
+| **tags** | `tags`, `tag` | Tag listing, counts, and filtering |
+| **tasks** | `tasks`, `task` | Task querying, filtering, and toggling |
+| **links** | `backlinks`, `links`, `unresolved`, `orphans`, `deadends` | Graph and link analysis |
+| **bookmarks** | `bookmarks` | Bookmark management |
+| **templates** | `templates`, `template:read`, `template:insert` | Template listing, rendering, insertion |
+| **plugins** | `plugins`, `plugin:enable`, `plugin:disable`, `plugin:install`, `plugin:reload` | Plugin management |
+| **sync** | `sync`, `sync:status`, `sync:history`, `sync:read`, `sync:restore`, `sync:deleted` | Obsidian Sync operations |
+| **themes** | `themes` | Theme management |
+| **dev** | `dev:screenshot`, `eval`, `dev:console`, `dev:errors` | Developer/debugging tools |
+| **vault** | `vault`, `vaults`, `version` | Vault info and metadata |
+| **other** | `outline`, `wordcount`, `recents`, `reload` | Utility commands |
+
+## Quick Reference — Most Common Commands
+
+### Reading & Writing Notes
+
+```bash
+obsidian read path="folder/note.md"
+obsidian create path="folder/note" content="# New Note"
+obsidian create path="folder/note" template="meeting-notes"
+obsidian append path="folder/note.md" content="New paragraph"
+obsidian prepend path="folder/note.md" content="Top content"
+obsidian move path="old/note.md" to="new/note.md"
+obsidian delete path="folder/note.md"
+obsidian delete path="folder/note.md" permanent
+```
+
+### Daily Notes
+
+```bash
+obsidian daily                          # Open today's daily note
+obsidian daily:read                     # Print content of today's note
+obsidian daily:append content="- [ ] New task"
+obsidian daily:prepend content="## Morning Notes"
+```
+
+### Search
+
+```bash
+obsidian search query="project alpha"
+obsidian search query="TODO" path="projects" limit=10
+obsidian search query="meeting" format=json
+obsidian search query="urgent" matches case
+```
+
+### Properties & Tags
+
+```bash
+obsidian properties path="note.md"
+obsidian property:set path="note.md" name="status" value="active"
+obsidian property:read path="note.md" name="status"
+obsidian property:remove path="note.md" name="draft"
+obsidian tags counts sort=count
+obsidian tag name="project/alpha"
+```
+
+### Tasks
+
+```bash
+obsidian tasks                          # All incomplete tasks
+obsidian tasks all                      # All tasks (done + todo)
+obsidian tasks done                     # Completed only
+obsidian tasks daily                    # Tasks in today's daily note
+obsidian task path="note.md" line=12 toggle
+```
+
+### Developer & Automation
+
+```bash
+obsidian eval code="app.vault.getFiles().length"
+obsidian dev:screenshot path="screenshot.png"
+obsidian dev:console limit=20
+obsidian dev:errors
+```
+
+## TUI Mode
+
+Running `obsidian` with no arguments launches an interactive TUI (Terminal User Interface):
+
+| Key | Action |
+|---|---|
+| `↑↓` | Navigate files |
+| `Enter` | Open file |
+| `/` | Search |
+| `n` | Create new file |
+| `d` | Delete file |
+| `r` | Rename file |
+| `q` | Quit |
+
+## Common Agent Patterns
+
+### Daily Journal Automation
+
+```bash
+# Append a timestamped entry
+obsidian daily:append content="## $(date '+%H:%M') — Status Update
+- Completed: feature branch merge
+- Next: code review for PR #42
+- Blocked: waiting on API credentials"
+```
+
+### Create Note from 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]]"
+```
+
+### Vault Analytics Script
+
+```bash
+obsidian files total                    # Total file count
+obsidian tags counts sort=count         # Most used tags
+obsidian tasks                          # Open tasks across vault
+obsidian orphans                        # Notes needing integration
+obsidian unresolved                     # Broken links to fix
+```
+
+### Search and Extract for AI Processing
+
+```bash
+obsidian search query="meeting notes" format=json | jq '.[] | .path'
+obsidian read path="meetings/standup.md" | grep "Action item"
+```
+
+### Sync Management
+
+```bash
+obsidian sync:status                    # Check sync health
+obsidian sync:history path="important.md"  # Version history
+obsidian sync:restore path="important.md" version=3  # Rollback
+```
+
+## Tips
+
+1. **Paths are vault-relative** — use `folder/note.md`, not absolute filesystem paths.
+2. **`create` paths omit `.md`** — the extension is added automatically.
+3. **`move` requires full target path** including `.md` extension.
+4. **Pipe-friendly** — plain text output works with `grep`, `awk`, `sed`, `jq`.
+5. **JSON output** — use `format=json` on search and file commands for machine parsing.
+6. **Stderr noise** — GPU/Electron warnings on headless are harmless; filter with `2>/dev/null`.
+7. **`daily:prepend`** inserts content after frontmatter, not at byte 0.
+8. **Use `eval`** to run arbitrary JavaScript against the Obsidian API (`app.*`).
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Empty output / hangs | Obsidian not running, or admin terminal (Windows) | Start Obsidian; use normal-privilege terminal |
+| Command not found | CLI not registered in PATH | Re-enable CLI in Settings; restart terminal |
+| Unicode errors | Fixed in v1.12.2+ | Update Obsidian |
+| Wrong vault targeted | Multi-vault ambiguity | Pass vault name as first arg |
+| IPC socket not found (Linux) | `PrivateTmp=true` in systemd | Set `PrivateTmp=false` |
+| Snap confinement issues | Snap restricts IPC | Use `.deb` package instead |

plugins/obsidian-cli/skills/obsidian-cli/references/command-reference.md

@@ -0,0 +1,409 @@
+# Obsidian CLI — Full Command Reference
+
+Complete reference for all official Obsidian CLI commands (v1.12+).
+
+**Syntax**: `obsidian [vault] <command> [subcommand] [key=value ...] [flags]`
+
+All parameters use `key=value` syntax. Quote values containing spaces: `content="hello world"`.
+
+---
+
+## Table of Contents
+
+1. [Files](#files)
+2. [Daily Notes](#daily-notes)
+3. [Search](#search)
+4. [Properties](#properties)
+5. [Tags](#tags)
+6. [Tasks](#tasks)
+7. [Links](#links)
+8. [Bookmarks](#bookmarks)
+9. [Templates](#templates)
+10. [Plugins](#plugins)
+11. [Sync](#sync)
+12. [Themes](#themes)
+13. [Developer](#developer)
+14. [Vault & System](#vault--system)
+
+---
+
+## Files
+
+File operations: read, write, create, move, delete, list.
+
+### Reading Notes
+
+```bash
+obsidian read path="folder/note.md"
+```
+
+Prints raw markdown content of a note to stdout. Path is vault-relative.
+
+### Creating Notes
+
+```bash
+obsidian create path="folder/note" content="# Title\n\nBody text"
+obsidian create path="folder/note" template="template-name"
+```
+
+- Path should **not** include `.md` — it is appended automatically.
+- Use `template=` to create from a template file.
+- Use `content=` to set initial content directly.
+
+### Appending & Prepending
+
+```bash
+obsidian append path="folder/note.md" content="Appended text"
+obsidian prepend path="folder/note.md" content="Prepended text"
+```
+
+- `append` adds content at the end of the file.
+- `prepend` adds content after the frontmatter (not at byte 0).
+
+### Moving & Renaming
+
+```bash
+obsidian move path="old/path/note.md" to="new/path/note.md"
+```
+
+- `to=` is the full vault-relative target path including the `.md` extension.
+- Can be used to move, rename, or both in a single command.
+
+### Deleting
+
+```bash
+obsidian delete path="folder/note.md"           # Moves to trash
+obsidian delete path="folder/note.md" permanent  # Permanent deletion
+```
+
+### File Discovery
+
+```bash
+obsidian files                       # List all files in vault
+obsidian files ext=md                # Filter by extension
+obsidian files folder="subfolder"    # Files in specific folder
+obsidian files total                 # Just the file count
+obsidian files format=json           # JSON output
+obsidian folders                     # List all folders
+obsidian file path="folder/note.md"  # File info (size, created, modified dates)
+```
+
+---
+
+## Daily Notes
+
+Operations on the daily note (requires Daily Notes core plugin enabled).
+
+```bash
+obsidian daily                           # Open today's daily note in Obsidian
+obsidian daily:read                      # Print today's daily note content to stdout
+obsidian daily:append content="text"     # Append content to today's note
+obsidian daily:prepend content="text"    # Prepend content (after frontmatter)
+```
+
+**Notes:**
+- `daily:prepend` inserts content after the frontmatter block, not at the very beginning.
+- If today's note doesn't exist, `daily` will create it (using the configured template if set).
+- Daily note format/folder are configured in Obsidian's Daily Notes plugin settings.
+
+---
+
+## Search
+
+Full-text search across the vault.
+
+```bash
+obsidian search query="search text"
+obsidian search query="text" path="folder"         # Scope to folder
+obsidian search query="text" limit=10               # Limit results
+obsidian search query="text" format=json            # JSON output
+obsidian search query="text" matches                # Include match context/snippets
+obsidian search query="text" case                   # Case-sensitive search
+```
+
+**Parameters:**
+- `query=` — Search term (required)
+- `path=` — Restrict search to a folder
+- `limit=` — Maximum number of results
+- `format=json` — Machine-readable JSON output
+- `matches` — Show matching line context
+- `case` — Enable case-sensitive matching
+
+---
+
+## Properties
+
+Manage frontmatter (YAML metadata) on notes.
+
+### Read All Properties
+
+```bash
+obsidian properties path="note.md"
+```
+
+### Read Single Property
+
+```bash
+obsidian property:read path="note.md" name="status"
+```
+
+### Set Property
+
+```bash
+obsidian property:set path="note.md" name="status" value="active"
+obsidian property:set path="note.md" name="tags" value="[project, alpha]"
+obsidian property:set path="note.md" name="date" value="2026-02-27"
+```
+
+### Remove Property
+
+```bash
+obsidian property:remove path="note.md" name="draft"
+```
+
+### Aliases
+
+```bash
+obsidian aliases path="note.md"
+```
+
+Lists all aliases defined in the note's frontmatter.
+
+---
+
+## Tags
+
+Tag discovery and filtering.
+
+```bash
+obsidian tags                          # List all tags in the vault
+obsidian tags counts                   # Tags with usage counts
+obsidian tags counts sort=count        # Sorted by frequency (most used first)
+obsidian tags path="note.md"           # Tags in a specific file
+obsidian tag name="project/alpha"      # List notes with a specific tag
+```
+
+**Notes:**
+- Nested tags are supported (e.g., `project/alpha`).
+- Tags from both frontmatter and inline `#tag` syntax are included.
+
+---
+
+## Tasks
+
+Query and manage checkbox tasks across the vault.
+
+### Querying Tasks
+
+```bash
+obsidian tasks                         # All incomplete tasks
+obsidian tasks all                     # All tasks (complete + incomplete)
+obsidian tasks done                    # Only completed tasks
+obsidian tasks path="note.md"          # Tasks in a specific file
+obsidian tasks daily                   # Tasks in today's daily note
+```
+
+### Toggling Task Status
+
+```bash
+obsidian task path="note.md" line=12 toggle
+```
+
+Toggles the checkbox on the specified line number between `- [ ]` and `- [x]`.
+
+---
+
+## Links
+
+Graph analysis and link management.
+
+```bash
+obsidian backlinks path="note.md"         # Notes linking TO this note
+obsidian backlinks path="note.md" counts  # With link counts per file
+obsidian links path="note.md"             # Outgoing links FROM this note
+obsidian unresolved                        # All unresolved [[wikilinks]]
+obsidian orphans                           # Notes with no incoming or outgoing links
+obsidian deadends                          # Notes with no outgoing links
+```
+
+---
+
+## Bookmarks
+
+Manage Obsidian bookmarks (requires Bookmarks core plugin).
+
+```bash
+obsidian bookmarks                     # List all bookmarks
+```
+
+Bookmarks commands let you view and manage bookmarked notes, searches, and groups. Use `obsidian bookmarks --help` for all available subcommands.
+
+---
+
+## Templates
+
+Work with note templates (requires Templates or Templater plugin).
+
+```bash
+obsidian templates                                      # List available templates
+obsidian template:read name="weekly-review"             # Read template content
+obsidian template:read name="weekly-review" resolve title="My Note"  # Render with variables
+obsidian template:insert name="weekly-review"           # Insert template into active file
+```
+
+**Parameters:**
+- `name=` — Template name (without path prefix or extension)
+- `resolve` — Process template variables
+- Title and other variables can be passed as `key=value` for template rendering.
+
+---
+
+## Plugins
+
+Manage community and core plugins.
+
+```bash
+obsidian plugins                       # List all installed plugins
+obsidian plugins:enabled               # Only enabled plugins
+obsidian plugins versions              # Plugins with version numbers
+obsidian plugin:enable id="canvas"     # Enable a plugin
+obsidian plugin:disable id="canvas"    # Disable a plugin
+obsidian plugin:install id="dataview"  # Install from community plugins
+obsidian plugin:reload id="my-plugin"  # Reload a plugin (useful for dev)
+```
+
+---
+
+## Sync
+
+Manage Obsidian Sync (requires active Sync subscription).
+
+```bash
+obsidian sync                                   # Show sync status summary
+obsidian sync on                                # Resume syncing
+obsidian sync off                               # Pause syncing
+obsidian sync:status                            # Detailed sync status
+obsidian sync:history path="note.md"            # Version history for a file
+obsidian sync:read path="note.md" version=3     # Read a specific version
+obsidian sync:restore path="note.md" version=3  # Restore a previous version
+obsidian sync:deleted                           # List files deleted via sync
+```
+
+---
+
+## Themes
+
+Manage appearance themes.
+
+```bash
+obsidian themes                        # List available/installed themes
+```
+
+Use `obsidian themes --help` for additional subcommands related to theme management (install, switch, etc.).
+
+---
+
+## Developer
+
+Debugging and development tools.
+
+### Screenshots
+
+```bash
+obsidian dev:screenshot path="screenshot.png"
+```
+
+Takes a screenshot of the Obsidian window and saves it.
+
+### JavaScript Evaluation
+
+```bash
+obsidian eval code="app.vault.getFiles().length"
+obsidian eval code="app.vault.getMarkdownFiles().map(f => f.path).join('\n')"
+```
+
+Executes arbitrary JavaScript in the Obsidian app context. Has access to the full Obsidian API (`app`, `app.vault`, `app.workspace`, `app.metadataCache`, etc.).
+
+### Console & Errors
+
+```bash
+obsidian dev:console limit=20          # Recent console output
+obsidian dev:errors                    # Recent error messages
+```
+
+---
+
+## Vault & System
+
+### Vault Information
+
+```bash
+obsidian vault                         # Current vault: name, path, file/folder counts
+obsidian vaults                        # List all known vaults
+```
+
+### Other Utilities
+
+```bash
+obsidian version                       # Obsidian version info
+obsidian outline path="note.md"        # Heading structure of a note
+obsidian wordcount path="note.md"      # Word and character count
+obsidian recents                       # Recently opened files
+obsidian reload                        # Reload the vault (re-index)
+```
+
+---
+
+## Output Formatting & Piping
+
+The CLI outputs plain text by default, ideal for piping into Unix tools:
+
+```bash
+# Count notes in a folder
+obsidian files folder="projects" | wc -l
+
+# Find notes with a specific tag, then read them
+obsidian tag name="urgent" | while read -r note; do
+  echo "=== $note ==="
+  obsidian read path="$note"
+done
+
+# Export search results as JSON and process with jq
+obsidian search query="meeting" format=json | jq '.[].path'
+
+# Filter console errors
+obsidian dev:console limit=50 | grep -i error
+```
+
+---
+
+## Multi-Vault Usage
+
+When working with multiple vaults, pass the vault name as the **first argument** (before the command):
+
+```bash
+obsidian "Personal" daily:read
+obsidian "Work" search query="standup"
+obsidian "Archive" files total
+```
+
+If the vault name contains spaces, quote it. The vault name must match what's shown in `obsidian vaults`.
+
+---
+
+## Headless / Server Setup (Linux)
+
+For running Obsidian CLI on a headless Linux server (useful for AI agent integration):
+
+1. Install the `.deb` package (not snap — snap confinement breaks IPC)
+2. Install and start `xvfb`: `Xvfb :5 -screen 0 1920x1080x24 &`
+3. Start Obsidian under xvfb: `DISPLAY=:5 obsidian &`
+4. Run CLI commands: `DISPLAY=:5 obsidian daily:read`
+
+**Systemd note**: If running as a service, ensure `PrivateTmp=false` so the IPC socket is accessible.
+
+**Stderr filtering**: Headless environments produce harmless GPU warnings. Filter with:
+
+```bash
+DISPLAY=:5 obsidian search query="test" 2>/dev/null
+```