obsidian-cli-inspector 1.0.3

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

Obsidian CLI Inspector

  • Note: THIS Feature currently is in alpha

GitHub Crates.io AUR stable version AUR unstable version AUR maintainer codecov

A local-first, read-only CLI/TUI for inspecting and querying Obsidian vaults. It helps developers quickly find notes, links, and tags without leaving the terminal.

What you can do

  • Search your vault with fast full‑text queries
  • Navigate backlinks, forward links, and unresolved links
  • Filter notes by tags (AND/OR)
  • Explore note relationships via graph view
  • Get suggestions for related notes
  • Surface large/bloated notes for cleanup
  • Use CLI for scripting or TUI for interactive browsing

Install

From crates.io

cargo install obsidian-cli-inspector

From source

git clone https://github.com/jingyi-zhao-01/obsidian-cli.git
cd obsidian-cli
cargo build --release

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

Quick start

  1. Create a config file and set your vault path:
mkdir -p ~/.config/obsidian-cli
cp config.toml.example ~/.config/obsidian-cli/config.toml

vault_path = "/path/to/your/obsidian/vault"
  1. Initialize and index your vault:
obsidian-cli-inspector init init
obsidian-cli-inspector index index
  1. Explore your notes:
obsidian-cli-inspector search notes "your query"
obsidian-cli-inspector search backlinks "Note Name"
obsidian-cli-inspector search tags productivity
obsidian-cli-inspector view stats

Note: If you try to run query commands before indexing, you'll get a clear error message:

  • Database not found - Run obsidian-cli-inspector init init first
  • Database is empty - Run obsidian-cli-inspector index index to index your vault

If search returns no results after indexing, run indexing again:

obsidian-cli-inspector index index --force

Use plain search text as the final argument. Example:

obsidian-cli-inspector search notes "Notes"

Common commands

# Init & Index
obsidian-cli-inspector init init [--force]
obsidian-cli-inspector index index [--dry-run] [--force] [--verbose]

# Search
obsidian-cli-inspector search notes "query" [--limit 20]
obsidian-cli-inspector search backlinks "Note Name"
obsidian-cli-inspector search links "Note Name"
obsidian-cli-inspector search unresolved
obsidian-cli-inspector search tags [tag-name] [--list]

# Analyze
obsidian-cli-inspector analyze related "Note Name" [--limit 10]
obsidian-cli-inspector analyze bloat [--threshold 50000] [--limit 10]

# View
obsidian-cli-inspector view stats
obsidian-cli-inspector view describe "Note Name"

# Diagnose
obsidian-cli-inspector diagnose orphans [--exclude-templates] [--exclude-daily]
obsidian-cli-inspector diagnose broken-links

# Interactive
obsidian-cli-inspector tui

CLI Contract

The CLI follows a structured command pattern. See docs/cli-contract.md for the full CLI contract, including the new group-based command structure and migration guide.

Machine Contracts (v1.1.0+)

For agent integration, use JSON output with deterministic contracts. See docs/machine-contract.md for full documentation.

Testing note: end-to-end contract tests are under tests/e2e and are skipped by default during regular make test runs. To run them, use:

make -C tests/e2e contracts

This command automatically prepares test data before running the suite.

Configuration

The minimum required setting is vault_path. Optional settings include database location, exclusions, and defaults. See config.toml.example for a complete list.

Status

The core indexing, parsing, chunking, and query features are in place. Advanced recommendations and hygiene features are evolving. See docs/TODOs.md for a user‑focused roadmap.

License

Apache-2.0

Contributing

Contributions are welcome. Please open an issue to discuss larger changes.