obsidian-cli-inspector 1.0.3

Local-first CLI/TUI for indexing and querying Obsidian vaults
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# Obsidian CLI Inspector


- Note: THIS Feature currently is in alpha


[![GitHub](https://img.shields.io/badge/GitHub-obsidian--cli-black?logo=github)](https://github.com/jingyi-zhao-01/obsidian-cli)
[![Crates.io](https://img.shields.io/crates/v/obsidian-cli-inspector.svg)](https://crates.io/crates/obsidian-cli-inspector)
[![AUR stable version](https://img.shields.io/aur/version/obsidian-cli-inspector?logo=arch-linux)](https://aur.archlinux.org/packages/obsidian-cli-inspector)
[![AUR unstable version](https://img.shields.io/aur/version/obsidian-cli-inspector-git?logo=arch-linux)](https://aur.archlinux.org/packages/obsidian-cli-inspector-git)
[![AUR maintainer](https://img.shields.io/aur/maintainer/obsidian-cli-inspector?logo=arch-linux)](https://aur.archlinux.org/packages/obsidian-cli-inspector)
[![codecov](https://codecov.io/gh/jingyi-zhao-01/obsidian-cli-inspector/branch/master/graph/badge.svg?token=4C0B7CEC8C)](https://codecov.io/gh/jingyi-zhao-01/obsidian-cli-inspector)


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

```bash
cargo install obsidian-cli-inspector
```

### From source

```bash
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:

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

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

2) Initialize and index your vault:

```bash
obsidian-cli-inspector init init
obsidian-cli-inspector index index
```

3) Explore your notes:

```bash
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:

```bash
obsidian-cli-inspector index index --force
```

Use plain search text as the final argument. Example:

```bash
obsidian-cli-inspector search notes "Notes"
```

## Common commands

```bash
# 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](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](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:
>
> ```bash
> 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](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](docs/TODOs.md) for a user‑focused roadmap.

## License

Apache-2.0

## Contributing

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