shit_admin: 2026-08-13 12:41:21
This commit is contained in:
shit_admin
@@ -0,0 +1,220 @@
|
||||
---
|
||||
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: claude, codex, opencode
|
||||
copilot-builtin-version: "2"
|
||||
copilot-upstream-revision: "a1dc48e68138490d522c04cbf5822214c6eb1202"
|
||||
---
|
||||
|
||||
# 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 <code>COPILOT_OBSIDIAN_CLI</code> when it can resolve one.
|
||||
Prefer that exact path over <code>obsidian</code> from <code>PATH</code>, 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:
|
||||
|
||||
~~~bash
|
||||
obsidian_cli="${COPILOT_OBSIDIAN_CLI:-obsidian}"
|
||||
"$obsidian_cli" version
|
||||
~~~
|
||||
|
||||
~~~powershell
|
||||
$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 <code>obsidian</code> 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:
|
||||
|
||||
~~~bash
|
||||
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 <code>vault=<name-or-id></code> before the command whenever the vault is
|
||||
known. Use <code>path=</code> for an exact vault-relative path. Use
|
||||
<code>file=</code> 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.
|
||||
|
||||
~~~bash
|
||||
obsidian vault="My Vault" backlinks path="Projects/Plan.md" format=json
|
||||
~~~
|
||||
|
||||
Parameters use <code>name=value</code>; 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: <code>daily</code>, <code>daily:path</code>,
|
||||
<code>daily:read</code>, <code>daily:append</code>,
|
||||
<code>daily:prepend</code>.
|
||||
- Typed properties and parsed metadata: <code>properties</code>,
|
||||
<code>property:read</code>, <code>property:set</code>,
|
||||
<code>property:remove</code>, <code>tags</code>, <code>tag</code>, and
|
||||
<code>aliases</code>. Supply a <code>type=</code> to
|
||||
<code>property:set</code> when the property is not plain text.
|
||||
- Tasks: <code>tasks</code> for indexed listing and <code>task</code> with a
|
||||
stable <code>ref=path:line</code> or exact file/line for status changes.
|
||||
- Link graph: <code>backlinks</code>, <code>links</code>,
|
||||
<code>unresolved</code>, <code>orphans</code>, and <code>deadends</code>.
|
||||
- Bases: <code>bases</code>, <code>base:views</code>, and
|
||||
<code>base:query</code>. Prefer <code>format=json</code> for structured agent
|
||||
consumption.
|
||||
- Templates: <code>templates</code> and <code>template:read ... resolve</code>
|
||||
when configured template resolution is required.
|
||||
- Live workspace state: <code>tabs ids</code> lists the currently open tabs and
|
||||
their IDs, while <code>workspace ids</code> shows the workspace tree and its
|
||||
item IDs.
|
||||
- Link-aware refactors: <code>move</code> and <code>rename</code> when the vault
|
||||
setting to update internal links should be honored.
|
||||
|
||||
### Inspect open notes
|
||||
|
||||
When the user asks about notes currently open in Obsidian:
|
||||
|
||||
~~~bash
|
||||
obsidian vault="My Vault" tabs ids
|
||||
obsidian vault="My Vault" workspace ids
|
||||
~~~
|
||||
|
||||
Use <code>tabs ids</code> 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 <code>.md</code>
|
||||
(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 <code>workspace ids</code> when tab groups or workspace hierarchy matter. Do
|
||||
not substitute <code>recents</code>, 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:
|
||||
|
||||
~~~bash
|
||||
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 <code>tabs ids</code>; 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:
|
||||
|
||||
~~~bash
|
||||
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
|
||||
|
||||
<code>commands</code> lists registered command IDs, including commands provided
|
||||
by plugins. Filter by an ID prefix, then execute the selected command with
|
||||
<code>command id=<command-id></code>. 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.
|
||||
|
||||
~~~bash
|
||||
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
|
||||
<code>plugin:reload id=<plugin-id></code> when needed. Never reload the
|
||||
Copilot plugin from a Copilot-hosted agent session.
|
||||
2. Inspect <code>dev:errors</code> and <code>dev:console level=error</code>.
|
||||
3. Verify UI state with <code>dev:screenshot path=...</code>,
|
||||
<code>dev:dom selector=...</code>, and <code>dev:css selector=...</code>.
|
||||
4. Use <code>dev:mobile on</code> only when mobile emulation is relevant, and
|
||||
turn it off afterward.
|
||||
|
||||
Read-only <code>eval</code> and <code>dev:cdp</code> 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 <code>kepano/obsidian-skills</code> at revision
|
||||
<code>a1dc48e68138490d522c04cbf5822214c6eb1202</code>. See <code>LICENSE</code>.
|
||||
Reference in New Issue
Block a user