pi-obsidian-cli

Dynamic pi extension wrapping the official Obsidian CLI (v1.13+) with fixed permission gating, 52 typed read-only catalog tools, audited fixed-purpose wrappers, prompt guidelines, and an interactive TUI browser.

Talks directly to the obsidian binary — no MCP server or Obsidian plugin dependency, with no extra setup beyond enabling the CLI in Obsidian.

Read the project story and design rationale: Safe Obsidian tools for Pi agents.

Safety Defaults

• Read-only permissions are enabled by default.
• No write-capable profiles are registered by default.
• Generic eval is disabled by default.
• DataviewJS requires explicit opt-in and confirmation.
• Fixed-purpose wrappers are audited separately from generic evaluation.

Quick Start

Install from npm (recommended)

pi install npm:pi-obsidian-cli

Install from git

pi install git:github.com/frNNcs/pi-obsidian-cli

Install from local clone (development)

git clone https://github.com/frNNcs/pi-obsidian-cli
cd pi-obsidian-cli
npm ci

Then install from the local path (run these from your terminal, not inside a pi session):

# Project-local (writes .pi/settings.json in the current project; the local path
# is referenced as-is — no copy, no symlink — and takes effect after /reload):
pi install -l /absolute/path/to/pi-obsidian-cli

# Global (writes pi's global settings.json; same no-copy behaviour):
pi install /absolute/path/to/pi-obsidian-cli

Note: Use absolute paths with pi install. Relative paths may not resolve correctly inside pi's runtime. If pi asks for trust, run /trust in a pi session or pass --approve on the CLI.

After installing, configure your vault in pi's settings.json:

{
  "obsidianCli": {
    "vault": "my-vault",
    "permissionMode": "read-only"
  }
}

Reload with /reload and you're done.

Prerequisites

• Node.js >= 22.19.0
• Obsidian 1.13+ running
• CLI enabled: Settings → General → Advanced → Command line interface
• obsidian binary on your PATH

Development

See docs/development.md for the full step-by-step circuit: clone → npm ci → typecheck → test → install locally → release.

Quick reference:

npm ci                    # clean install from lockfile
npm run check             # TypeScript type-check (tsc --noEmit)
npm run pack:dry          # validate packaging integrity

# Test with pi — loads ONLY this extension, no duplicates:
pi --no-extensions -e ./index.ts

What You Get

52 Typed Read-Only Catalog Tools

The current Obsidian CLI catalog exposes 52 read-only commands as dedicated tools with typed parameters, structured JSON/TSV output, and contextual defaults (active file, vault):

| Category | Tools | |----------|-------| | Files & Folders | obsidian_read, obsidian_files, obsidian_folders, obsidian_file, obsidian_folder, obsidian_outline | | Search | obsidian_search, obsidian_search_context | | Tasks & Tags | obsidian_tasks, obsidian_tags, obsidian_tag | | Properties | obsidian_properties, obsidian_property_read | | Links & Graph | obsidian_links, obsidian_backlinks, obsidian_orphans, obsidian_deadends, obsidian_unresolved | | Bases | obsidian_bases, obsidian_base_query, obsidian_base_views | | Daily Notes | obsidian_daily, obsidian_daily_path | | Sync | obsidian_sync_status, obsidian_sync_history, obsidian_sync_read, obsidian_sync_deleted | | History | obsidian_history, obsidian_history_list, obsidian_history_read | | Plugins & Themes | obsidian_plugins, obsidian_plugin, obsidian_themes, obsidian_theme | | Workspace | obsidian_workspace, obsidian_tabs, obsidian_recents | | Special | obsidian_active_file, obsidian_resolve_link |

Audited Fixed-Purpose Wrappers

These wrappers are separate from the read-only catalog and can be enabled without enabling generic eval:

• obsidian_excalidraw_export
• obsidian_excalidraw_mermaid
• obsidian_active_file
• obsidian_resolve_link
• obsidian_dataview_query
• obsidian_tasks_query
• obsidian_daily creation

obsidian_dataviewjs_run remains separate and opt-in because it evaluates user-supplied JavaScript and always requires confirmation.

Permission Gating (Fixed by Code, Not Prompt)

Three modes with risk classification (read / write / danger):

{
  "obsidianCli": {
    "permissionMode": "read-only",
    "exclude": ["eval", "command", "dev:*", "restart", "reload"],
    "confirmDestructive": true
  }
}

• read-only — only read commands (default, safe)
• all — everything minus exclude
• custom — only commands matching include (minus exclude)

Blocked commands fail with an explanation of exactly which setting to change — the policy cannot be negotiated from the prompt.

Fixed-script tools and confirmation. Audited fixed-purpose wrappers run when allowFixedScripts is enabled (the default) without enabling generic eval. Fixed wrappers do not prompt themselves; write-capable operations use the central confirmation path. The general obsidian tool and arbitrary eval commands remain governed by permission mode and exclude.

Interactive TUI Browser

Run /obsidian to open the browser:

• Filter with / + Tab autocomplete (longest common prefix, cycles with Tab/Shift+Tab)
• Risk badges (◦ read · ● write · ▲ danger)
• Argument editor with inline flag reference
• Scrollable output with TSV column alignment
• m cycle permission mode (session-only)
• v set vault · r rediscover catalog

Inline mode: /obsidian read path=Notes/hello.md runs directly.

Prompt Guidelines

Dedicated tools carry concise usage guidance (promptGuidelines) telling the LLM to use them instead of built-in read/bash/grep/ls/find for vault operations.

Configuration Reference

| Key | Default | Description | |-----|---------|-------------| | binary | "obsidian" | Path to the CLI binary | | autoLaunch | false | Allow the CLI to launch the Obsidian GUI when the app is not running. Disabled by default; keep Obsidian open before using obsidian_* tools. | | vault | (active) | Default vault name or id | | permissionMode | "read-only" | "read-only" / "all" / "custom" | | include | [] | Patterns for custom mode ("read", "base:*") | | exclude | ["eval","command","dev:cdp","dev:debug","restart","reload","plugin:install","plugin:uninstall","theme:install","theme:uninstall"] | Always-blocked patterns | | exposeReadOnlyTools | true | Register typed tools per command | | promptSnippets | true | Show tools in system prompt "Available tools" | | confirmDestructive | true | Confirm write/danger in TUI; reject them without a UI | | timeoutMs | 30000 | Per-invocation timeout | | maxOutputBytes | 51200 | Output returned to LLM | | statusBar | true | Footer: vault · mode · catalog | | preferJson | true | Request format=json where supported | | contextMode | "active-tab" | "active-tab"/"manual" — default file/folder from active tab | | resolveWikilinks | true | Resolve [[wikilinks]] to vault paths | | allowFixedScripts | true | Enable audited wrappers without enabling generic eval | | allowDataviewJs | false | Opt in to user-supplied DataviewJS execution; requires confirmation | | toolProfiles | {} | Optional named profiles; write-capable profiles are never registered by default |

Settings live under "obsidianCli" in pi's main settings.json.

By default, the extension performs a process pre-flight and fails fast when Obsidian is not running, so calling a tool never opens the GUI unexpectedly. Set "autoLaunch": true only if you explicitly want the CLI to retain its automatic app-launch behavior.

Config file locations (pi's search order):

• Global: ~/.config/pi/agent/settings.json (or ~/.pi/agent/settings.json if configured)
• Project: .pi/settings.json (relative to the project root)

When the project is trusted, project settings override global values for keys such as permissionMode and include; exclude entries are always additive. Treat trusted project settings as permission-bearing configuration and review them before enabling trust.

Architecture

The editable Excalidraw source is available at docs/architecture.excalidraw.

Catalog Discovery

obsidian __completions returns a JSON map of every command, including usage, description, and flags. The catalog varies per vault because plugins can add namespaces such as sync:* and base:*; discovery falls back to fallback-catalog.json when the app is unreachable.

Dependencies

Zero runtime dependencies. All pi packages and typebox are peerDependencies — they are provided by the pi runtime at execution time, not bundled with this extension.

| Dependency | Role | Provided by | |------------|------|-------------| | @earendil-works/pi-coding-agent | Extension API, events, types | pi runtime | | @earendil-works/pi-agent-core | Core SDK types | pi runtime | | @earendil-works/pi-ai | AI provider interface | pi runtime | | @earendil-works/pi-tui | TUI key bindings, text utils | pi runtime | | typebox | Tool parameter schemas | pi runtime |

In devDependencies (for tsc --noEmit only):

• @types/node — Node.js type definitions
• typescript — the type checker itself
• All five peer packages at the pinned versions used to develop against

Troubleshooting

"Extension not trusted" / tools don't appear

Run /trust in pi to trust the extension. If running from the CLI with --no-extensions -e, use:

pi --no-extensions -e ./index.ts --approve

Duplicate tools after installing from local path

If you previously had a manual copy in ~/.config/pi/agent/extensions/obsidian-cli/, pi will load both. Remove the manual copy:

rm -rf ~/.config/pi/agent/extensions/obsidian-cli
# or, if your pi uses ~/.pi:
rm -rf ~/.pi/agent/extensions/obsidian-cli

Then /reload in pi. Verify with /tools — you should see each obsidian_* tool exactly once.

"pi: command not found" or "pi install not recognized"

Ensure @earendil-works/pi-coding-agent is installed globally:

npm install -g @earendil-works/pi-coding-agent

Obsidian CLI connection errors

• Make sure Obsidian is running before invoking any tool
• Check that Command line interface is enabled in Obsidian settings
• Verify the obsidian binary is on your PATH: which obsidian
• If the binary has a different name/path, set obsidianCli.binary in settings

Local path install doesn't pick up changes

pi install -l /path registers the local path in pi's settings (.pi/settings.json for project-local, or global settings.json). The path is referenced as-is — files are neither copied nor symlinked into pi's extension directory. Changes to the source files should be picked up after /reload. If not:

1. Verify the path is recorded correctly: check extensions in your .pi/settings.json or global settings.json
2. Force a reload: /reload
3. If all else fails, reinstall: pi install -l /absolute/path/to/pi-obsidian-cli

Known Quirks

• daily:path double-slash: The upstream Obsidian CLI returns paths like Daily//2026/07-julio/2026-07-31.md. obsidian_daily fixes this; regular daily:path shows the raw value.
• create exits 0 on error: The CLI always exits 0. Errors are detected from output text patterns.
• Catalog drift: Regenerate fallback-catalog.json after Obsidian updates: obsidian __completions > fallback-catalog.json

Release Checklist

1. npm run check passes on main
2. npm run pack:dry shows correct file list
3. Manual smoke test: pi --no-extensions -e ./index.ts
4. Bump version in package.json (semver)
5. Commit and tag: git tag vX.Y.Z && git push origin main --tags
6. Verify install from git: pi install git:github.com/frNNcs/pi-obsidian-cli
7. (Optional) Publish to npm: npm publish → pi install npm:pi-obsidian-cli

License

MIT