odcli 0.1.7

A small CLI for reading and writing notes in a local Obsidian vault.

odcli

odcli is a command-line tool for reading and writing notes in a local Obsidian vault.

It works directly on Markdown files inside the vault, so you can use it without any private Obsidian API.

Install

From PyPI:

pip install odcli

Or with uv:

uv tool install odcli

After installation, both command names are available:

odcli --help
obsidian-cli --help

Quickstart

If your vault is already in a common location, odcli can usually find it automatically:

odcli check
odcli list

If you want to set the vault explicitly:

export OBSIDIAN_VAULT="/path/to/MyVault"
odcli check

You can also override the vault per command:

odcli --vault "/path/to/MyVault" list

Remote Vault over SSH

You can operate on an Obsidian vault stored on another machine over SSH.

Example:

odcli \
  --ssh-host your-server \
  --ssh-user your-user \
  --vault /path/to/ObsidianVault \
  list

Read a remote note:

odcli \
  --ssh-host your-server \
  --ssh-user your-user \
  --vault /path/to/ObsidianVault \
  read Inbox/today.md

Write a remote note:

odcli \
  --ssh-host your-server \
  --ssh-user your-user \
  --vault /path/to/ObsidianVault \
  write Inbox/today.md --content "# Remote note"

Optional SSH flags:

• --ssh-port
• --ssh-identity

In SSH mode, --vault or OBSIDIAN_VAULT should point to the remote vault path.

Common Commands

Read a note:

odcli read Inbox/today.md

Read specific lines:

odcli read-lines Inbox/today.md 3 8

Create or overwrite a note:

odcli write Inbox/today.md --content "# Today"

Replace a line range:

odcli write-lines Inbox/today.md 3 4 --content "- replaced\n- lines\n"

Append content:

odcli append Inbox/today.md --content "\n- new item"

Search across the vault:

odcli search "project alpha"

Skill Install

odcli can install helper skills for local coding tools.

Install into Codex:

odcli plugin install codex-skill

Install into Claude Code:

odcli plugin install claude-skill

Install both:

odcli plugin install all-skills

Installed paths:

• Codex: ~/.codex/skills/odcli/SKILL.md
• Claude Code: ~/.claude/skills/odcli/SKILL.md

Vault Discovery

Resolution priority:

1. --vault /path/to/vault
2. OBSIDIAN_VAULT
3. The most recently opened vault recorded by local Obsidian config
4. Common default directories

Built-in default locations:

• macOS: ~/Documents/Obsidian Vault
• macOS: ~/Documents/Obsidian
• macOS iCloud: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents
• Windows: %USERPROFILE%\\Documents\\Obsidian Vault
• Windows: %USERPROFILE%\\Documents\\Obsidian

Command Summary

check

Validate that the vault exists and report whether .obsidian is present.

list

List Markdown notes in the vault.

Optional arguments:

• --limit N

read

Read a note.

Arguments:

• note_path: path relative to the vault root

write

Overwrite a note. Parent directories are created automatically if needed.

Arguments:

• note_path
• --content TEXT
• --stdin

Optional arguments:

• --create-only

read-lines

Read a line range. Line numbers are 1-based and inclusive.

Arguments:

• note_path
• start_line
• end_line

write-lines

Replace a line range. Line numbers are 1-based and inclusive.

Arguments:

• note_path
• start_line
• end_line
• --content TEXT
• --stdin

append

Append content to the end of a note.

Arguments:

• note_path
• --content TEXT
• --stdin

search

Search across all Markdown notes in the vault.

Arguments:

• query
• --case-sensitive

Global Options

• --vault
• --ssh-host
• --ssh-user
• --ssh-port
• --ssh-identity

For Developers

Run from source:

cd path/to/obsidian_cli
uv sync
uv run odcli --help

Run tests:

cd path/to/obsidian_cli
uv run python -m unittest discover -s tests

Build distributions:

cd path/to/obsidian_cli
uv build