aiobsidian 0.3.0

Async Python client for Obsidian CLI and Local REST API

aiobsidian

Async Python client for Obsidian. CLI-first: works out of the box with the Obsidian CLI (v1.12+). Optional REST support via the Local REST API plugin.

---

Installation

pip install aiobsidian

For REST API support (requires httpx):

pip install aiobsidian[rest]

Quick start

CLI (primary)

import asyncio
from aiobsidian import ObsidianCLI

async def main():
    async with ObsidianCLI("MyVault") as cli:
        # Read a note
        content = await cli.vault.read("notes/hello.md")
        print(content)

        # Search the vault
        results = await cli.search.query("python")

        # List tags
        tags = await cli.tags.list()

        # Daily note
        await cli.daily.append("- [ ] New task")

asyncio.run(main())

REST (optional)

import asyncio
from aiobsidian import ObsidianClient

async def main():
    async with ObsidianClient("your-api-key") as client:
        status = await client.system.status()
        print(status.versions.obsidian)

        content = await client.vault.get("notes/hello.md")
        print(content)

asyncio.run(main())

Features

CLI resources

Resource	Access	Description
vault	cli.vault	Read, create, append, prepend, move, rename, delete, list
daily	cli.daily	Daily note operations
search	cli.search	Full-text search
properties	cli.properties	YAML frontmatter properties
tags	cli.tags	Tag listing, lookup, rename
links	cli.links	Outgoing links, backlinks, unresolved, orphans
tasks	cli.tasks	Task listing, creation, completion

REST resources

Resource	Access	Description
vault	client.vault	CRUD operations on any file
active	client.active	Operations on the currently open file
periodic	client.periodic	Daily, weekly, monthly, quarterly, yearly notes
commands	client.commands	List and execute Obsidian commands
search	client.search	Simple text search, Dataview DQL, JsonLogic
open	client.open	Open files in Obsidian UI
system	client.system	Server status, OpenAPI spec

General

• Full async/await support
• Pydantic v2 models for type-safe responses
• Custom exception hierarchy for both CLI and REST errors
• Context manager lifecycle management
• No external dependencies for CLI (only stdlib)

Documentation

Full documentation is available at kudato.github.io/aiobsidian.

Contributing

Contributions are welcome! Please see the Contributing Guide for details.

License

MIT