notekey

CLI utilities for working with Markdown notes in an Obsidian vault.

notekey can:

• initialize a folder with an Obsidian .base file and a matching Markdown note
• search vault notes by tag, filename, or content
• read a single note, discover its headings, or read a specific heading section

Requirements

• Python 3.11+
• An Obsidian vault directory containing a .obsidian/ folder

Installation

After the package is published to PyPI:

pip install notekey

Usage

notekey init [path]
notekey search [path] [--tags TAGS] [--filename NAME] [--content TEXT]
notekey read FILENAME [--sections | --section SECTION] [--json]

For init, omitting path uses the current directory.

For search and read, omitting path uses the OBSIDIAN_VAULT environment variable. If that variable is not set, it uses the current directory.

export OBSIDIAN_VAULT="/path/to/your/vault"

Initialize a note folder

cd /path/to/vault/Projects/MyProject
notekey init

Or pass the target folder explicitly:

notekey init /path/to/vault/Projects/MyProject

This creates:

• MyProject.base
• MyProject.md

Add extra base filters with comma-separated tags:

notekey init /path/to/vault/Projects/MyProject --tags python,docs

Overwrite existing generated files with:

notekey init /path/to/vault/Projects/MyProject --force

Search notes

Search by tag:

notekey search --tags python

Search by multiple tags. Files must match all tags:

notekey search --tags python,web

Search by filename:

notekey search --filename flask

Search by content:

notekey search --content pandas

Use = for exact matches:

notekey search --tags "=python"
notekey search --filename "=deep/hidden-note"

Read a note or section

notekey read flask-app

For an exact filename match:

notekey read "=flask-app"

List the headings in a note before choosing a section:

notekey read flask-app --sections

Example output:

flask-app.md

  1  # Flask App
  2  ## Setup
  3  ## Open Questions
  4  ### API Shape

Read a section by its 1-based outline number:

notekey read flask-app --section 3

Read a section by a case-insensitive title substring:

notekey read flask-app --section api

Section reads include the selected heading and its nested child headings, stopping at the next heading of the same or higher level. If a title search matches multiple headings, notekey prints the matching outline entries so you can retry with a number or a more specific title.

For exact section title matching, prefix the section query with =:

notekey read flask-app --section "=API Shape"

Section discovery and section reads can return JSON:

notekey read flask-app --sections --json
notekey read flask-app --section 4 --json

Development

Run tests with:

pytest

Build distribution files with:

python -m build

Upload is intentionally manual. Use TestPyPI or PyPI with your API token when ready.