obsidian-search

Obsidian Search

Use Obsidian CLI to convert natural language needs into executable queries, then give concise conclusions based on the output. Prefer reusing obsidian search、search:context、tasks、tags、properties、backlinks、files、outline and other ready-made commands, rather than hand-writing file traversal logic.

Workflow

Execute in the following order:

1. Determine the type of result the user really wants: a file list, matching context, tasks, tags, properties, link relationships, the content of a certain note, or a combined query.
2. Read references/cli-query-patterns.md, and choose the most fitting command pattern.
3. When assembling commands, prefer using:
   • query= pass in the user's keyword or search expression
   • path= narrow the directory scope
   • file= resolve the target note by file name
   • format=json prefer using when a stable summary is needed
   • limit= control the result size to avoid overly long output
4. Use Bash to execute the Obsidian CLI command.
5. If search:context executes successfully but returns no content, do not immediately assume "no results"; first switch to the same keyword's obsidian search to verify whether matching files exist, then decide whether to supplement with read、outline and other follow-up commands.
6. Read the results and answer the user's question directly, do not dump large chunks of terminal output verbatim.
7. If the first round of results is too broad or clearly ambiguous, run another round of more specific queries based on the results.

Query Decision

First match the following scenarios:

• User wants to "find notes containing a certain word" -> obsidian search
• User wants to "see which lines/context the matching word appears in" -> obsidian search:context
• User wants to "find to-dos/completed items" -> obsidian tasks
• User wants to "see tags, how many times a certain tag is used" -> obsidian tags or obsidian tag
• User wants to "see property distribution or a certain file's properties" -> obsidian properties
• User wants to "see who links to this note" -> obsidian backlinks
• User wants to "see who this note links to" -> obsidian links
• User wants to "list files under a certain directory" -> obsidian files folder=<path>
• User wants to "see document structure/heading hierarchy" -> obsidian outline
• User wants to "directly read the content of a certain matching note" -> first search/files locate, then obsidian read

If the user's question is essentially "summarize the distribution or viewpoints of a certain topic in the knowledge base", prefer a two-step approach:

1. obsidian search or obsidian search:context narrow the scope
2. For the few most relevant files, use obsidian read、outline or backlinks to supplement information before summarizing

Command Construction Rules

• Put vault=<name> at the very front of the command, and only use it when switching vaults is necessary.
• Wrap values containing spaces in double quotes, for example query="会议纪要"。
• file= is suitable for resolving by note name; when precise location is needed, switch to path=。
• When the user says "recent" or "latest", the CLI itself does not directly support sorting by time; first query candidate files, then supplement the judgment with vault tools.
• When the user wants to count quantities, prefer adding total or choose format=json and then summarize yourself.
• When the user wants machine-readable results, prefer format=json; when the user only needs a quick answer, the default text format can be used.
• Do not return too many files at once; unless the user explicitly requests the full set, generally add limit=10 or smaller.
• In the current environment, search:context may exhibit the situation of "command succeeds but no output"; when this happens, prefer falling back to obsidian search, and if necessary then run read。

Summary rules

• Give the conclusion first, then the basis.
• When there are few results, directly list the key files or key lines.
• When there are many results, cluster and summarize themes, tags, directory distribution, or high-frequency patterns.
• If there are no results, clearly state "not found" and give broader query terms that can be tried next.
• If search:context has no output but search has hits, you should clearly tell the user "relevant files have been found, but the current CLI did not return context lines", and instead summarize the candidate files.
• If the query semantics are not clear enough, first do the safest round of search, then decide based on the results whether to ask a follow-up question.

Output format

By default, organize the answer in this order:

1. Answer the user's question in one sentence
2. Key findings (2-5 items)
3. If necessary, give the commands that were executed
4. If necessary, suggest a more precise direction for the next query

Reference materials

• references/cli-query-patterns.md: common query commands, parameter selection, and natural language to command mapping