obsidian-cli-inspector 0.0.4

Local-first CLI/TUI for indexing and querying Obsidian vaults
Documentation

Obsidian CLI Inspector

A local-first, read-only CLI/TUI tool for vault hygiene and querying Obsidian vaults. Built with Rust for speed and reliability.

Features

  • Fast full-text search using SQLite FTS5
  • Link analysis - Find backlinks, forward links, and unresolved references
  • Tag management - Query notes by tags with AND/OR operations
  • Graph navigation - Explore connections between notes
  • Smart suggestions - Find related notes without explicit links
  • Vault hygiene - Detect bloated notes and suggest refactoring
  • Incremental indexing - Fast re-indexing by tracking changes
  • CLI + TUI - Scriptable commands and interactive interface

Status

Phase 0 (Foundations) - Complete

  • Project builds as a single Rust binary
  • SQLite database with FTS5 support
  • Configuration via config.toml
  • CLI command structure defined

Upcoming Phases:

  • Phase 1: Vault scanning and change detection
  • Phase 2: Obsidian markdown parsing (wikilinks, frontmatter, tags)
  • Phase 3: Document chunking for retrieval
  • Phase 4: Full database schema implementation
  • Phase 5: Incremental indexing
  • Phase 6: Query layer (search, links, tags)
  • Phase 7: Relevance suggestions
  • Phase 8: Bloat detection and refactoring

Installation

Prerequisites

  • Rust 1.70+ (install via rustup)

Build from source

git clone https://github.com/yourusername/obsidian-cli.git
cd obsidian-cli
cargo build --release

The binary will be at target/release/obsidian-cli.

Quick Start

1. Create configuration

Copy the example config and customize it:

mkdir -p ~/.config/obsidian-cli
cp config.toml.example ~/.config/obsidian-cli/config.toml

Edit ~/.config/obsidian-cli/config.toml and set your vault path:

vault_path = "/path/to/your/obsidian/vault"

2. Initialize database

obsidian-cli init

3. Index your vault

obsidian-cli index

4. Start exploring

# Search notes
obsidian-cli search "your query"

# Find backlinks
obsidian-cli backlinks "Note Name"

# List notes by tag
obsidian-cli tags productivity

# Show vault statistics
obsidian-cli stats

Usage

# Initialize or reinitialize database
obsidian-cli init [--force]

# Index vault (scan and parse all files)
obsidian-cli index [--dry-run] [--force] [--verbose]

# Full-text search
obsidian-cli search "query" [--limit 20]

# Find backlinks to a note
obsidian-cli backlinks "Note Name"

# Find forward links from a note
obsidian-cli links "Note Name"

# List unresolved links
obsidian-cli unresolved-links

# List notes by tag
obsidian-cli tags [tag-name] [--all]

# Suggest related notes
obsidian-cli suggest "Note Name" [--limit 10]

# Detect bloated notes
obsidian-cli bloat [--threshold 50000] [--limit 10]

# Show statistics
obsidian-cli stats

# Launch interactive TUI
obsidian-cli tui

# Explore graph
obsidian-cli graph ["Note Name"] [--depth 2]

Configuration

The configuration file (config.toml) supports:

  • vault_path: Path to your Obsidian vault (required)
  • database_path: Where to store the index (default: ~/.local/share/obsidian-cli/index.db)
  • exclude.patterns: Directories/patterns to skip (default: .obsidian/, .git/, .trash/)
  • search.default_limit: Default search result limit
  • graph.max_depth: Maximum graph traversal depth
  • llm: Optional LLM configuration for Q&A features

See config.toml.example for details.

Architecture

Tech Stack

  • Rust - Performance and reliability
  • SQLite - Local storage with FTS5 for full-text search
  • rusqlite - SQLite bindings
  • clap - CLI argument parsing
  • toml - Configuration

Data Model

  • Notes - File metadata, content hash, frontmatter
  • Links - Wikilinks, embeds, markdown links with resolution status
  • Tags - Inline and frontmatter tags
  • Chunks - Text segments for retrieval and search
  • FTS Index - Full-text search over chunks

Development

Build and test

# Build
cargo build

# Run tests
# Check formatting (CI parity)
rustfmt --edition 2021 --check $(git ls-files '*.rs')

# Lint (CI parity)
cargo clippy --all-targets --all-features -- -D warnings

# Convenience aliases (same as CI)
cargo fmt-check
cargo lint

Git hooks (format/lint/tests)

Enable the repo hooks (pre-commit: format + lint, pre-push: tests):

git config core.hooksPath .githooks

If you clone to a new machine, re-run the command above.

Project Structure

src/
├── main.rs       # Entry point
├── cli.rs        # Command definitions
├── config.rs     # Configuration loading
└── db.rs         # Database schema and operations

Roadmap

See TODOs.md for detailed roadmap and implementation checklist.

License

MIT OR Apache-2.0

Contributing

Contributions welcome! Please open an issue first to discuss major changes.