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
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
- Obsidian must be running
- Local REST API plugin by Adam Coddington installed and enabled
- Dataview plugin by Michael Brenan installed and enabled
- OBSIDIAN_API_KEY environment variable set with API key from plugin settings
- 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
