Obsidian CLI Inspector

Note: THIS Feature currently is in alpha

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

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"

Initialize and index your vault:

obsidian-cli-inspector init init
obsidian-cli-inspector index index

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.

obsidian-cli-inspector 1.0.1