ObsidianBase

ObsidianBase

Preferred: Use obsidian base:query (see the ObsidianCLI skill) when Obsidian is running. This skill documents the standalone obsidian-base binary for offline/fallback use.

Resolve .base files against the vault — the same declarative queries [[Obsidian]] renders internally. Returns matching notes as [[JSONL]] or file paths, enabling [[Claude]] to see exactly what the user sees in their [[Obsidian Base]] views.

When to Use

• User asks "what does this [[Base]] show?" or "what books are on my reading list?"
• You need to query vault notes by [[frontmatter]] properties, [[tags]], paths, or [[wikilinks]]
• A .base file is referenced in conversation and you want to resolve it
• You need filtered, sorted note lists for any vault operation

Tool

Binary: Modules/forge-obsidian/bin/obsidian-base

The binary auto-discovers the vault root by walking up from the .base file looking for .obsidian/. It reads the [[YAML]] query, walks all .md files, evaluates filters against [[frontmatter]] + file metadata, applies sorts, and emits results.

Dependencies

Dependency	Required	Purpose
[[Rust]] (cargo)	Yes	Builds the obsidian-base binary on first run (lazy compilation)
[[jq]]	No	Post-filter [[JSONL]] output (optional)

The binary is self-contained after compilation — no runtime dependencies beyond the standard library.

Usage

# Default: JSONL output (one JSON object per matched note, per view)
Modules/forge-obsidian/bin/obsidian-base "/path/to/File.base"

# Resolve only a specific view
Modules/forge-obsidian/bin/obsidian-base "/path/to/File.base" --view "Table"

# File paths only (one per line) — for piping to other tools
Modules/forge-obsidian/bin/obsidian-base "/path/to/File.base" --paths

# Count matches
Modules/forge-obsidian/bin/obsidian-base "/path/to/File.base" --paths | wc -l

# Filter JSONL with jq
Modules/forge-obsidian/bin/obsidian-base "/path/to/File.base" | jq 'select(.tags | contains(["type/item"]))'

Intent-to-Flag Mapping

User Says	Flag	Effect
"show me what this Base has"	(default)	[[JSONL]] output with all view columns
"which view", "only the Table view"	--view "Name"	Resolve a single named view
"just the files", "list the paths"	--paths	One file path per line
"how many notes match"	--paths | wc -l	Count of matching notes
"filter by tag/property"	pipe to [[jq]]	Post-filter [[JSONL]] with [[jq]] expressions

Output Format

JSONL (default)

Each line is a self-contained [[JSON]] object:

{"view":"Table","file":"Library/Books/The Pragmatic Programmer.md","name":"The Pragmatic Programmer","tags":["type/item/book"],"item.read":true}

Fields include:

• view — which view matched this note
• file — vault-relative path
• name — note name (stem, no extension)
• Plus any columns defined in the view's order list ([[frontmatter]] properties, file metadata)

Paths mode (--paths)

Library/Books/The Pragmatic Programmer.md
Library/Books/Designing Data-Intensive Applications.md

Finding .base Files

Base files live alongside the content they query. Common locations:

# Find all .base files in a vault
find /path/to/vault -name "*.base" -type f

Expression Surface

The .base filter [[DSL]] supports:

Category	Examples
File properties	file.name, file.path, file.ext, file.folder, file.tags, file.links
Frontmatter	property.key or bare key
Context	this.file.name, this.file.path, this.file.folder
String methods	.startsWith(), .endsWith(), .contains(), .toString(), .slice(n,m)
Functions	contains(collection, value), file.hasTag("tag"), file.hasLink("link")
Operators	!=, ! (prefix negation)
Combinators	and: […], or: […] ([[YAML]]-level boolean logic)

Limitations

• this context — this.file.* refers to the note embedding the [[Base]], not the .base file itself. When resolving template [[Bases]] (e.g., Daily.base) from CLI, this references the .base file's location. Pass a note context mentally when interpreting results from template Bases.
• Performance — walks the entire vault (~1s for large vaults). Results are not cached.
• Formulas — .unique(), .filter(), .asFile() are not yet supported.
• Rendering — no view layout (cards, list, board). Output is data only.

Constraints

• Always use the full path to the .base file (absolute or project-relative)
• Check [[TLP]] before reading vault files referenced in output
• [[JSONL]] output can be large — pipe through [[jq]], head, or wc -l for summaries
• Do not modify .base files without the user's explicit request — they define the user's [[Obsidian]] views