From 986ff986d2e29490c9b706fef840637e99795f36 Mon Sep 17 00:00:00 2001 From: pablo-mano Date: Tue, 3 Mar 2026 23:08:04 +0100 Subject: [PATCH] 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 --- .claude-plugin/plugin.json | 2 +- .../obsidian-cli/.claude-plugin/plugin.json | 2 +- .../obsidian-cli/skills/obsidian-cli/SKILL.md | 12 +++++++++++ .../references/command-reference.md | 20 +++++++++++++++++++ skills/obsidian-cli/SKILL.md | 12 +++++++++++ .../references/command-reference.md | 20 +++++++++++++++++++ 6 files changed, 66 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ce6bf7b..f4f1105 100644 --- a/.claude-plugin/plugin.json +++ b/.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" }, diff --git a/plugins/obsidian-cli/.claude-plugin/plugin.json b/plugins/obsidian-cli/.claude-plugin/plugin.json index ce6bf7b..f4f1105 100644 --- a/plugins/obsidian-cli/.claude-plugin/plugin.json +++ b/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" }, diff --git a/plugins/obsidian-cli/skills/obsidian-cli/SKILL.md b/plugins/obsidian-cli/skills/obsidian-cli/SKILL.md index 0af77ee..06be55c 100644 --- a/plugins/obsidian-cli/skills/obsidian-cli/SKILL.md +++ b/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` | diff --git a/plugins/obsidian-cli/skills/obsidian-cli/references/command-reference.md b/plugins/obsidian-cli/skills/obsidian-cli/references/command-reference.md index 543e4e4..3493dff 100644 --- a/plugins/obsidian-cli/skills/obsidian-cli/references/command-reference.md +++ b/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) diff --git a/skills/obsidian-cli/SKILL.md b/skills/obsidian-cli/SKILL.md index 0af77ee..06be55c 100644 --- a/skills/obsidian-cli/SKILL.md +++ b/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` | diff --git a/skills/obsidian-cli/references/command-reference.md b/skills/obsidian-cli/references/command-reference.md index 543e4e4..3493dff 100644 --- a/skills/obsidian-cli/references/command-reference.md +++ b/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)