Document three real-world gotchas in v1.3.0 (issue #1)

- property:set stores list values as strings (not YAML arrays)
- eval requires single-line JS; add temp-file workaround
- Multi-vault "Name" command may fail; document fallback

Added Tips 10-12 to SKILL.md, inline callouts to command-reference.md,
two new Troubleshooting rows, and version bump to 1.3.0.

Fixes #1

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

plugins/obsidian-cli/.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.2.0",
+  "version": "1.3.0",
   "author": {
     "name": "pablo-mano"
   },

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

@@ -229,6 +229,16 @@ obsidian command id="dataview:dataview-force-refresh-views"
 7. **`daily:prepend`** inserts content after frontmatter, not at byte 0.
 8. **Use `eval`** to run arbitrary JavaScript against the Obsidian API (`app.*`).
 9. **`template:insert`** inserts into the currently active file in the Obsidian UI — it does not accept a `path=` parameter. If no file is open, it returns `Error: No active editor. Open a file first.` To create a file from a template via CLI, use `obsidian create path="..." template="..."` instead.
+10. **`property:set` stores list values as strings** — `value="tag1, tag2"` writes a literal comma-separated string, not a YAML array. For proper array fields, edit the note's frontmatter directly (e.g. via `read` → modify → `create --force`) or use `eval` to call the Obsidian API.
+11. **`eval` requires single-line JavaScript** — multiline JS passed inline fails with a token error. Write the script to a temp file instead:
+    ```bash
+    cat > /tmp/obs.js << 'JS'
+    var files = app.vault.getMarkdownFiles();
+    files.length;
+    JS
+    obsidian eval code="$(cat /tmp/obs.js)"
+    ```
+12. **Multi-vault targeting may not work in all environments** — `obsidian "My Vault" command` can return `Error: Command "My Vault" not found` on some setups. If this happens, omit the vault name (CLI targets the most recently active vault) and switch vaults manually in the Obsidian UI.
 
 ## Troubleshooting
 
@@ -240,3 +250,5 @@ obsidian command id="dataview:dataview-force-refresh-views"
 | 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 |
+| Multi-vault `"Name" command` fails | Vault name matching issue | Omit vault name; target most recent vault |
+| `property:set` list value is a string | CLI stores value as-is | Edit frontmatter directly or use `eval` |

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

@@ -196,6 +196,10 @@ obsidian property:set path="note.md" name="tags" value="[project, alpha]"
 obsidian property:set path="note.md" name="date" value="2026-02-27"
 ```
 
+> **Note:** `property:set` always stores `value=` as a string. Passing `value="[project, alpha]"` writes
+> the literal string `[project, alpha]`, not a YAML array. For true array-typed properties (e.g. `tags`),
+> edit the note's frontmatter directly or use `eval` with the Obsidian API.
+
 ### Remove Property
 
 ```bash
@@ -487,6 +491,17 @@ 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.).
 
+> **Multiline scripts:** Passing multiline JavaScript inline fails with "Invalid or unexpected token".
+> Write the code to a temp file and use command substitution instead:
+>
+> ```bash
+> cat > /tmp/obs.js << 'JS'
+> var files = app.vault.getMarkdownFiles();
+> files.map(f => f.path).join('\n');
+> JS
+> obsidian eval code="$(cat /tmp/obs.js)"
+> ```
+
 ### Console & Errors
 
 ```bash
@@ -611,6 +626,11 @@ obsidian "Archive" files total
 
 If the vault name contains spaces, quote it. The vault name must match what's shown in `obsidian vaults`.
 
+> **Compatibility note:** On some environments, `obsidian "My Vault" command` returns
+> `Error: Command "My Vault" not found`. If this occurs, omit the vault name — the CLI will target
+> the most recently active vault. Switch vaults in the Obsidian UI before running CLI commands
+> when targeting a specific vault.
+
 ---
 
 ## Headless / Server Setup (Linux)