Obsidian SDK

Give your AI coding tools a local brain. A developer-friendly TypeScript SDK that wraps the Obsidian CLI, enabling AI assistants like Claude Code to interact with your Obsidian vault programmatically.

Overview

Obsidian SDK transforms Obsidian from a note-taking app into a programmable knowledge base. Build automation workflows, create custom AI integrations, and give your coding assistant access to your personal wiki—all with a clean, typed API.

Why Obsidian SDK?

• Developer-Friendly — Fully typed TypeScript with intelligent autocomplete and comprehensive JSDoc documentation
• Local Knowledge Base — Transform Obsidian into an AI-accessible brain for Claude Code, Cursor, or any LLM
• Automation Made Easy — Script your vault operations, batch rename files, manage templates, automate daily notes
• Next-Level Note Taking — Programmatic access to search, linking, templates, and vault management
• Zero Configuration — Works out of the box with any existing Obsidian vault

Features

| Category | Capabilities | |----------|--------------| | Notes | Create, read, update, delete, and search notes programmatically | | Files | List vault contents, search within files, manage file operations | | Search | Full-text search with context highlighting and regex support | | Linking | Manage internal links, backlinks, and graph connections | | Daily Notes | Automate daily note creation and navigation | | Vaults | Create, open, switch between multiple vaults | | Templates | Apply, create, and manage note templates | | Plugins | Enable, disable, and manage Obsidian plugins | | History | Access and navigate note revision history | | Sync | Monitor vault sync status | | Metrics | Get vault statistics and analytics | | Random | Random note picker for spaced repetition and review | | Dev Tools | Developer utilities for vault exploration |

Installation

npm install obsidian-sdk

Requirements

• Node.js 18+
• Obsidian CLI installed and available in PATH

Quick Start

Initialize the SDK

import { Obsidian } from "obsidian-sdk";

// Connect to your vault
const obsidian = new Obsidian({ vault: "myVault" });

List All Notes

const files = await obsidian.files.list();
console.log(`Found ${files.length} files`);

Search Notes

const results = await obsidian.search.query("machine learning");
results.forEach(r => console.log(r.file, r.score));

Create a Note

await obsidian.notes.create({
  name: "My New Note",
  extension: "md",
  content: "# Hello World\n\nThis is my first programmatically created note!"
});

Open Daily Note

await obsidian.daily.open();

Get Vault Statistics

const metrics = await obsidian.metrics.vault();
console.log(`Vault size: ${metrics.size}`);

API Reference

Obsidian Class

The main entry point for all vault operations.

const obsidian = new Obsidian({ vault: "vaultName" });

| Property | Type | Description | |----------|------|-------------| | notes | Notes | CRUD operations for notes | | files | Files | File listing and search | | search | Search | Full-text search | | linking | Linking | Internal links and backlinks | | daily | Daily | Daily notes management | | vaults | Vaults | Multi-vault operations | | templates | Templates | Template management | | plugins | Plugins | Plugin management | | history | History | Note revision history | | sync | Sync | Sync status | | metrics | Metrics | Vault analytics | | random | Random | Random note picker | | dev | Dev | Developer utilities |

Advanced Usage

Building a Knowledge Base Search Tool

import { Obsidian } from "obsidian-sdk";

const obsidian = new Obsidian({ vault: "knowledge-base" });

async function searchKnowledgeBase(query: string) {
  const results = await obsidian.search.query(query, {
    context: 2,
    includeScore: true,
  });

  return results.map(r => ({
    title: r.file,
    snippet: r.context,
    score: r.score,
  }));
}

// Usage with Claude Code
const searchResults = await searchKnowledgeBase("TypeScript generics");

Batch File Operations

// Rename all notes with a prefix
const files = await obsidian.files.list();

for (const file of files) {
  if (!file.startsWith("Z-")) {
    await obsidian.fileOps.rename({
      file,
      newName: `Z-${file}`,
    });
  }
}

Automate Daily Journal

async function createMorningJournal() {
  const date = new Date().toISOString().split('T')[0];
  
  await obsidian.daily.open();
  await obsidian.templates.apply("morning-journal");
}

Export Vault for AI Context

async function exportForAI(limit = 50) {
  const files = await obsidian.files.list();
  const recentFiles = files.slice(0, limit);
  
  const context = await Promise.all(
    recentFiles.map(f => obsidian.notes.read(f))
  );
  
  return context.join("\n\n---\n\n");
}

Error Handling

All SDK methods throw ObsidianError on failure. Always wrap calls in try-catch:

import { Obsidian, ObsidianError } from "obsidian-sdk";

const obsidian = new Obsidian({ vault: "myVault" });

try {
  const content = await obsidian.notes.read("NonExistent.md");
} catch (err) {
  if (err instanceof ObsidianError) {
    console.error(`Obsidian error: ${err.message}`);
    console.error(`Exit code: ${err.exitCode}`);
  }
}

Known Limitations

• No streaming support — Large output commands are loaded completely into memory
• No built-in configuration API — Settings file manipulation is not yet exposed
• Single vault context — Operations target one vault at a time

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run development harness
npm run dev

Running Tests

npm test

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

ISC