Obsidian/copilot/skills/obsidian-cli/SKILL.md

---

name: obsidian-cli description: Use the official Obsidian CLI when a task needs Obsidian's running app, index, configured features, command registry, or developer runtime. Use for currently open notes and tabs, workspace state, daily notes, typed properties, tasks, links/backlinks, Bases queries, template resolution, link-aware moves, plugin commands, and plugin/theme debugging; do not use it for ordinary filesystem operations. license: MIT metadata: copilot-enabled-agents: opencode, claude, codex copilot-builtin-version: "2"

copilot-upstream-revision: "a1dc48e681"

Obsidian CLI

Use the CLI only for behavior that depends on Obsidian's running application, indexes, settings, command registry, or developer runtime. Use normal shell filesystem tools for ordinary file reads, writes, directory listing, and text search.

Capability probe and fallback

Copilot exposes the terminal-capable executable from the running Obsidian installation as COPILOT_OBSIDIAN_CLI when it can resolve one. Prefer that exact path over obsidian from PATH, and always invoke it as a quoted executable rather than constructing a command string. Before relying on the CLI, probe it using the active shell:

obsidian_cli="${COPILOT_OBSIDIAN_CLI:-obsidian}"
"$obsidian_cli" version

$obsidianCli = if ($env:COPILOT_OBSIDIAN_CLI) { $env:COPILOT_OBSIDIAN_CLI } else { "obsidian" }
& $obsidianCli version

A command being present on PATH is not sufficient: the probe must exit successfully. Use the selected executable in place of obsidian in the examples below, resolving it again in a later shell call when necessary. If the probe fails, continue with ordinary filesystem tools where they can satisfy the request. Briefly tell the user only when the missing runtime capability matters. Do not install Obsidian, change PATH, register the CLI, or raise the plugin's minimum Obsidian version on the user's behalf.

The CLI requires a compatible Obsidian installer and a running app. Commands can differ by version, so inspect live help before using a command whose syntax is not already established:

obsidian help <command>

When a request truly needs the runtime capability and the probe fails, tell the user to open Obsidian and enable Settings → General → Command line interface using a compatible installer. Leave registration and any platform repair steps to the user.

Target precisely

Put vault=<name-or-id> before the command whenever the vault is known. Use path= for an exact vault-relative path. Use file= only when Obsidian's wikilink-style name resolution is desired. Do not rely on the active vault or active file when a precise target is available.

obsidian vault="My Vault" backlinks path="Projects/Plan.md" format=json

Parameters use name=value; boolean flags have no value. Quote values containing spaces or shell-special characters.

High-value indexed and configured operations

Use live help for exact parameters, then prefer these families when they add meaning beyond raw files:

• Configured daily notes: daily, daily:path, daily:read, daily:append, daily:prepend.
• Typed properties and parsed metadata: properties, property:read, property:set, property:remove, tags, tag, and aliases. Supply a type= to property:set when the property is not plain text.
• Tasks: tasks for indexed listing and task with a stable ref=path:line or exact file/line for status changes.
• Link graph: backlinks, links, unresolved, orphans, and deadends.
• Bases: bases, base:views, and base:query. Prefer format=json for structured agent consumption.
• Templates: templates and template:read ... resolve when configured template resolution is required.
• Live workspace state: tabs ids lists the currently open tabs and their IDs, while workspace ids shows the workspace tree and its item IDs.
• Link-aware refactors: move and rename when the vault setting to update internal links should be honored.

Inspect open notes

When the user asks about notes currently open in Obsidian:

obsidian vault="My Vault" tabs ids
obsidian vault="My Vault" workspace ids

Use tabs ids as the source of truth for open tabs. Keep entries verbatim and classify them only when the output provides enough evidence:

• a Markdown note has an explicit vault path ending in .md (case-insensitive)
• another file-backed tab has an explicit vault path with a different extension
• a non-file view, such as search, graph, settings, or a plugin view, has no vault path

Do not infer a path from a display title, view type, or tab ID, and do not discard entries that cannot be classified. For a request about open notes, extract the Markdown paths while retaining the other tabs as workspace context. Use workspace ids when tab groups or workspace hierarchy matter. Do not substitute recents, which includes files that are no longer open.

If the tab output does not expose paths or view types clearly, correlate its tab IDs with this read-only, structured workspace query:

obsidian vault="My Vault" eval code='JSON.stringify((()=>{const tabs=[];const active=app.workspace.getMostRecentLeaf();app.workspace.iterateAllLeaves(leaf=>{const path=leaf.view.file?.path??null;tabs.push({id:leaf.id,title:leaf.getDisplayText(),viewType:leaf.view.getViewType(),path,kind:path===null?"view":path.toLowerCase().endsWith(".md")?"markdown":"file",active:leaf===active})});return tabs})())'

The workspace query also returns sidebar and floating leaves. Only call an entry an open tab when its ID appears in tabs ids; retain query-only entries separately as workspace context. Preserve tab entries that have no matching workspace entry instead of guessing their identity.

If the user asks for the single currently focused note and the tab output does not identify it, use a read-only app query:

obsidian vault="My Vault" eval code="app.workspace.getMostRecentLeaf()?.view.file?.path ?? ''"

Use normal filesystem tools only for explicit paths returned by Obsidian, and choose a reader appropriate to the file type. Do not read every open note when paths or titles alone answer the request.

Obsidian and plugin commands

commands lists registered command IDs, including commands provided by plugins. Filter by an ID prefix, then execute the selected command with command id=<command-id>. Never guess a command ID when it can be discovered. Do not execute a discovered command whose effect is prohibited by the host-session rules below.

obsidian vault="My Vault" commands filter="my-plugin:"
obsidian vault="My Vault" command id="my-plugin:run-action"

Plugin and theme development

Use the CLI as the first choice for runtime verification after the normal build or test command has produced artifacts:

1. For a plugin other than Copilot, reload with plugin:reload id=<plugin-id> when needed. Never reload the Copilot plugin from a Copilot-hosted agent session.
2. Inspect dev:errors and dev:console level=error.
3. Verify UI state with dev:screenshot path=..., dev:dom selector=..., and dev:css selector=....
4. Use dev:mobile on only when mobile emulation is relevant, and turn it off afterward.

Read-only eval and dev:cdp queries are appropriate for state that the documented inspection commands cannot expose. Keep expressions small and return serializable values. Treat any expression or CDP call that mutates application state as a risky operation requiring explicit user intent.

Preserve the host session

Never reload or restart the Obsidian app or window from an agent session. Never reload, disable, or uninstall the Copilot plugin that is hosting the agent. In particular, do not use:

• any CLI command that reloads or restarts the app, window, or renderer
• any plugin reload, disable, or uninstall operation targeting Copilot
• any restricted-mode change
• a command ID, JavaScript expression, or CDP call that performs an equivalent app, window, renderer, or Copilot-plugin teardown

These actions terminate the in-flight agent and can discard its work. This is a hard prohibition, not a confirmation-gated operation. If verification requires one, finish all non-destructive checks and tell the user to perform the reload manually after the agent session has ended.

Risky operations require explicit intent

Do not perform the following merely because they are available:

• permanent deletion
• local-history or Sync restoration
• publishing or unpublishing
• plugin or theme installation/uninstallation
• mutating JavaScript evaluation or CDP calls

Confirm that the user's request clearly authorizes the exact target and effect. Prefer reversible variants, such as trash-backed deletion, when they satisfy the request. Explicit intent does not override the host-session prohibition above.

Exclusions

Do not teach or use the TUI, clipboard output, undocumented flags, platform registration repairs, or CLI equivalents of generic filesystem operations in this skill.

Attribution

Adapted from kepano/obsidian-skills at revision a1dc48e68138490d522c04cbf5822214c6eb1202. See LICENSE.