obsidian-search-tool

Obsidian Search Tool

A CLI tool that searches an Obsidian vault through the Obsidian Local REST API using Dataview Query Language (DQL) - TABLE queries only - and JsonLogic queries.

Table of Contents

• About
• Use Cases
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Library Usage
• API Limitations and Known Issues
• Development
• Resources
• License

About

What is Obsidian Search Tool?

obsidian-search-tool is a command-line interface for searching through Obsidian vaults using the Obsidian Local REST API plugin. It provides search-only operations using:

• Dataview DQL: TABLE queries with powerful filtering, sorting, and grouping
• JsonLogic: JSON-based programmatic queries for tags, frontmatter, and content

Why This CLI Tool?

Agent-Friendly Design - Built specifically for integration with AI agents (Claude Code), automation pipelines, and reusable building blocks:

• ReAct Loops: Structured commands and error messages enable AI agents to reason and act effectively
• Composable Architecture: JSON stdout and logs stderr allow easy piping and integration
• Reusable Building Blocks: Commands serve as primitives for Claude Code skills, MCP servers, or custom workflows
• Dual-Mode Operation: Use as CLI or importable Python library
• Production Quality: Type-safe, tested, with comprehensive error handling

Use Cases

• 📚 Knowledge Base Management - Search and organize notes by tags, topics, or metadata
• 💻 Source Code Intelligence - Query code snippets and technical documentation
• 🔍 Semantic Search - Find notes by content, frontmatter fields, or relationships
• 🎯 RAG Applications - Retrieve context for AI-powered applications
• 🤖 Agent Integration - Build Claude Code skills and MCP servers for vault access

Features

• Search Operations:

  • Dataview DQL TABLE queries (FROM, WHERE, SORT, LIMIT)
  • JsonLogic queries for programmatic access (content search with "in" operator)
  • Tag search, frontmatter field search, content search, file path search
  • Access to implicit fields (file.name, file.mtime, file.size, file.tags, etc.)
  • Note: GROUP BY, FLATTEN not supported by Obsidian Local REST API

• Multiple Output Formats:

  • JSON (default) - Machine-readable for automation
  • Markdown text - Human-readable with metadata
  • Pretty-printed tables - Visual inspection of structured data

• CLI-First Design:

  • Flat command structure for simplicity
  • Stdin support for piping queries
  • Rich error messages with solutions
  • Comprehensive help with examples

• Production Quality:

  • Type-safe with strict mypy
  • Tested with pytest
  • Linted with ruff
  • Comprehensive error handling
  • Environment-based configuration

Prerequisites

Required

1. Obsidian must be running
2. Local REST API plugin by Adam Coddington installed and enabled
3. Dataview plugin by Michael Brenan installed and enabled
4. OBSIDIAN_API_KEY environment variable set with API key from plugin settings
5. Python 3.14+ and uv package manager

Installation

From Source

# Clone repository
git clone https://github.com/dnvriend/obsidian-search-tool.git
cd obsidian-search-tool

# Install globally with uv
uv tool install .

# Verify installation
obsidian-search-tool --version

With mise (Recommended for Development)

cd obsidian-search-tool
mise trust
mise install
uv sync
uv tool install .

Configuration

Get API Key