Skip to content

Quick Start

This guide walks you through the most common operations with aiobsidian.

CLI

Creating a CLI instance

Use ObsidianCLI as an async context manager:

import asyncio
from aiobsidian import ObsidianCLI

async def main():
    async with ObsidianCLI("MyVault") as cli:
        files = await cli.vault.list()
        print(f"{len(files)} files in vault")

asyncio.run(main())

Available CLI resources

Resource Access Description
vault cli.vault Read, create, append, prepend, move, rename, delete, list
daily cli.daily Daily note: read, create, append, prepend, path
search cli.search Full-text search
properties cli.properties YAML frontmatter properties: list, read, set, remove
tags cli.tags Tags: list, get notes by tag, rename
links cli.links Outgoing links, backlinks, unresolved, orphans
tasks cli.tasks Tasks: list, create, complete, toggle
commands cli.commands List and execute Obsidian commands
templates cli.templates List, read, insert templates
bookmarks cli.bookmarks List and add bookmarks
plugins cli.plugins Plugin management
themes cli.themes Theme management
snippets cli.snippets CSS snippet management
sync cli.sync Obsidian Sync operations
publish cli.publish Obsidian Publish operations
history cli.history Local file history
workspaces cli.workspaces Workspace management
hotkeys cli.hotkeys Hotkey operations
outline cli.outline Document outline (headings)
random cli.random Random note
aliases cli.aliases Note aliases
bases cli.bases Obsidian Bases / databases
system cli.system Version, reload, restart, vaults
tabs cli.tabs Tab management, recents
web cli.web Open URLs in web viewer
dev cli.dev Developer/debugging tools

Reading and writing notes

# Read a note
content = await cli.vault.read("notes/hello.md")

# Create a note
await cli.vault.create("notes/new.md", "# New Note\n\nContent here.")

# Append to a note
await cli.vault.append("notes/hello.md", "\n## New section")

Working with tags

# List all tags
tags = await cli.tags.list(sort="count")

# Get notes with a specific tag
notes = await cli.tags.get("python")

# Rename a tag across the vault
await cli.tags.rename("old-tag", "new-tag")

# Get outgoing links from a note
links = await cli.links.outgoing("notes/hello.md")

# Get backlinks to a note
backlinks = await cli.links.incoming("notes/hello.md")

# Find broken links
broken = await cli.links.unresolved()

# Find orphan notes
orphans = await cli.links.orphans()

Working with tasks

# List all tasks
tasks = await cli.tasks.list()

# Create a task
await cli.tasks.create("Buy milk", tags="shopping,errands")

# Complete a task
await cli.tasks.complete("task-id")

Searching

results = await cli.search.query("python asyncio")
for result in results:
    print(result)

Daily notes

# Read today's daily note
content = await cli.daily.read()

# Append to today's note
await cli.daily.append("- [x] Completed task")

# Get the path
path = await cli.daily.path()

REST

Creating a REST client

Use ObsidianClient as an async context manager to ensure the HTTP connection is properly closed:

import asyncio
from aiobsidian import ObsidianClient

async def main():
    async with ObsidianClient(api_key="your-api-key") as client:
        status = await client.system.status()
        print(status.authenticated)  # True

asyncio.run(main())

Available REST resources

Resource Access Description
vault client.vault Read, create, update, and delete vault files
active client.active Operate on the currently open file
periodic client.periodic Access daily, weekly, monthly, quarterly, yearly notes
commands client.commands List and execute Obsidian commands
search client.search Search vault content
open client.open Open files in the Obsidian UI
system client.system Server status and OpenAPI spec

Reading a note

# Get raw Markdown
content = await client.vault.get("Notes/hello.md")
print(content)

# Get structured JSON (with frontmatter, tags, stats)
from aiobsidian import ContentType

note = await client.vault.get("Notes/hello.md", content_type=ContentType.NOTE_JSON)
print(note.frontmatter)
print(note.tags)

Creating a note

await client.vault.update("Notes/new-note.md", "# My New Note\n\nHello, world!")

Searching

results = await client.search.simple("python asyncio")
for result in results:
    print(f"{result.filename} (score: {result.score})")
    for match in result.matches or []:
        print(f"  ...{match.context}...")

Executing commands

commands = await client.commands.list()
for cmd in commands[:5]:
    print(f"{cmd.id}: {cmd.name}")

# Execute a specific command
await client.commands.execute("editor:toggle-bold")

Next steps