obi

Read-only CLI that surfaces structured data from Obsidian vaults for LLM consumption. Default output is TOON, with --json fallback.

System Requirements

• Binary users: No dependencies -- standalone executable
• Package manager: Bun runtime required
• Supported OS: macOS, Linux, Windows

Installation

Option 1: Package Manager

Requires Bun runtime.

bun add -g @butttons/obi

Option 2: Pre-built Binary

Download the latest binary for your platform from the releases page:

# macOS (ARM64)
curl -L https://github.com/butttons/obi/releases/latest/download/obi-darwin-arm64 -o obi
chmod +x obi
sudo mv obi /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/butttons/obi/releases/latest/download/obi-darwin-x64 -o obi
chmod +x obi
sudo mv obi /usr/local/bin/

# Linux
curl -L https://github.com/butttons/obi/releases/latest/download/obi-linux-x64 -o obi
chmod +x obi
sudo mv obi /usr/local/bin/

# Windows
# Download obi-windows-x64.exe from the releases page and add to PATH

Option 3: Build from Source

git clone https://github.com/butttons/obi.git
cd obi
bun install
bun run build
sudo mv dist/obi /usr/local/bin/

Updating

Package Manager

bun add -g @butttons/obi@latest

Binary

Re-run the curl command from Option 2 to download the latest release.

Usage

# List available vaults
obi vaults

# Vault structure
obi map --vault Work

# Read a note
obi read "Projects/my-project.md"

# Search vault content
obi search "deployment"

# Filter by frontmatter
obi query --type worker --tag billing

Commands

Orientation

Command	Description
obi vaults	List all available vaults with paths and note counts
obi map	Vault structure: folders and files with frontmatter metadata
obi context	Current workspace state: active file, recent files, search, tabs
obi schema	Property types, types in use, tags in use

Navigation

Command	Description
obi read <path>	Frontmatter, body, outgoing and incoming links
obi read <path> -s "Heading"	Extract only the section under a heading
obi toc <path>	Heading tree for a note
obi links <path>	Outgoing links, incoming links, 2-hop connections
obi list [folder]	Folder contents with title, type, tags

Query

Command	Description
obi query --type <value>	Filter notes by frontmatter fields
obi query --tag <value>	Filter by tag
obi query -f key=value	Generic frontmatter filter (repeatable)
obi search <term>	Content search with file, line, and context
obi recent [--limit N]	Notes sorted by updated_at
obi unread	Notes where read: false in frontmatter

Global Flags

Flag	Description
--json	Output JSON instead of TOON
--vault <name>	Target vault by name

Vault Resolution

1. OBI_VAULTS_PATH env var pointing to the vaults parent directory
2. Falls back to ~/Library/Mobile Documents/iCloud~md~obsidian/Documents
3. If neither exists, errors with setup instructions

When --vault is omitted:

1. If cwd is inside a vault, uses that vault
2. Otherwise uses default_vault from global config
3. Otherwise errors listing available vaults

Config

Global

~/.config/obi/config.json

{
  "default_vault": "Work",
  "vaults": {
    "Work": { "ignore": ["templates/"] }
  }
}

Per-Vault

<vault>/.obsidian/obi.json

{
  "ignore": ["templates/"]
}

Per-vault config wins over global when both exist.

Build

# npm distribution
bun run build:npm

# compiled binary
bun run build

# all platforms
bun run build:all

License

MIT