apple-notes-cli/README.md

apple-notes-cli

Search, read, and export Apple Notes from the terminal by reading the local Notes database directly — no AppleScript, no UI automation, no cloud API.

Built for the common case: you mostly want to look things up, not write them. Recalling what you noted about a project, finding the meeting where a decision was made, pulling every note that mentions a library — that is read-heavy work, and it is exactly where the existing tooling is weakest.

$ apple-notes search "kubernetes" -n 3
   4821  2026-09-08 14:02   Work/Infra/Cluster upgrade notes  (7x)
         …drain the node before the kubernetes control plane restarts…
   3907  2026-08-30 09:15   Work/Runbooks/On-call  (2x)
         …kubernetes events are the fastest way to see why a pod is pending…

$ apple-notes recent --since 2d
   4830  2026-09-09 15:59   Work/Meeting notes
   4829  2026-09-09 13:54   Personal/Reading list

Why not AppleScript

Almost every Apple Notes integration drives Notes.app through AppleScript (osascript): the memo CLI does — its get_memo.py and id_search_memo.py shell out to it — as do the apple-notes skill in OpenClaw and Hermes, which wrap memo, and Claude's own desktop Notes connector.

AppleScript is the right choice for writing — it is Apple's supported interface and it keeps CloudKit sync intact. But for reading it carries costs that are easy to miss. Measured on a real 818-note store:

Operation	AppleScript	apple-notes-cli
Enumerate folders and count notes	1.85 s	—
Fetch one note body	0.325 s	—
Full-text search every note	~266 s (extrapolated)	0.11 s

Full-text search is impractical, so tools quietly stop doing it. first note whose id is "…" is an unindexed linear scan inside Notes.app, so each body costs about a third of a second. Reading all 818 would take over four minutes. Faced with that, memo searches titles only — its search_memo.py builds a {title: id} map and fuzzy-matches against the keys, never the bodies. So memo notes -s "kubernetes" finds notes called "kubernetes", not the notes that discuss it. The OpenClaw skill exposes this as "fuzzy search" with no indication that note contents are not searched.

Caching trades freshness for speed, usually silently. memo caches its note list to ~/.cache/memo/notes_cache.json with a 300-second TTL, so a note you just wrote can be invisible for five minutes. Neither the skill documentation nor the CLI surfaces this, so an agent asking "what did I note today?" can be handed a confidently stale answer.

Other friction that comes with the AppleScript path:

• It needs Notes.app. The app gets launched or scripted in the background, and if it hangs or shows a modal, the integration hangs with it.
• It needs Automation permission (System Settings → Privacy & Security → Automation), granted interactively per client app. That makes unattended use — cron, CI, an SSH session — awkward or impossible.
• Bodies arrive as HTML, so every tool bolts on an HTML-to-Markdown converter and inherits its fidelity bugs.
• macOS only, and it cannot run from the web or iOS at all.
• Per-note round trips. Reading N notes means N osascript invocations, each paying process startup plus Apple Events IPC.

Reading the SQLite store sidesteps all of it: one query, then in-memory decoding. Full-text search over everything takes ~0.11 s, which is why this tool needs no cache and always reflects the live database.

The trade-off is that this only reads; AppleScript remains the right way to create and edit notes. The two compose well — see Reading is all it does.

Install

Requires macOS and Python 3.10+.

Just ask your agent

If you use Claude Code, Claude Desktop, or any coding agent, point it at this file and it has everything it needs:

Read https://github.com/ingjieye/apple-notes-cli/blob/main/README.md and set it up, including the skill.

The CLI

uv tool install git+https://github.com/ingjieye/apple-notes-cli
# or
pipx install git+https://github.com/ingjieye/apple-notes-cli

Run it straight from a clone without installing:

git clone https://github.com/ingjieye/apple-notes-cli && cd apple-notes-cli
uv run python -m apple_notes_cli recent

macOS may ask you to grant your terminal access to the Notes container the first time. Nothing here needs Full Disk Access on its own.

The agent skill

skills/apple-notes/SKILL.md teaches an agent to use this CLI — when to reach for it, how to page from search results to full note bodies, and what its limits are. Drop it in place:

mkdir -p ~/.claude/skills/apple-notes
curl -fsSL https://raw.githubusercontent.com/ingjieye/apple-notes-cli/main/skills/apple-notes/SKILL.md \
  -o ~/.claude/skills/apple-notes/SKILL.md

Use .claude/skills/ inside a project instead of ~/.claude/skills/ to scope it to that project. Then ask your agent things like "what did I note about the cluster migration?" or "找一下我记过的会议决定".

Setup steps, if you are an agent reading this

# 1. macOS only; bail out early elsewhere.
[ "$(uname)" = "Darwin" ] || { echo "macOS required"; exit 1; }

# 2. Install the CLI (uv preferred, pipx as fallback).
if command -v uv >/dev/null; then
  uv tool install git+https://github.com/ingjieye/apple-notes-cli
else
  pipx install git+https://github.com/ingjieye/apple-notes-cli
fi

# 3. Install the skill.
mkdir -p ~/.claude/skills/apple-notes
curl -fsSL https://raw.githubusercontent.com/ingjieye/apple-notes-cli/main/skills/apple-notes/SKILL.md \
  -o ~/.claude/skills/apple-notes/SKILL.md

# 4. Verify against the real store. Exit 1 from `search` just means no match.
apple-notes folders | head -5
apple-notes recent -n 3

If step 4 reports the database is missing, Notes.app has never been launched on this machine. If it raises a permission error, the terminal needs access to the Notes container — that is a macOS prompt the user has to accept, not something you can grant.

Commands

apple-notes search <query>   full-text search across every note body
apple-notes recent           list recently modified notes
apple-notes show <id>        print one note as Markdown
apple-notes folders          list folders with note counts
apple-notes export <dir>     export everything to Markdown files

search

apple-notes search "OpenTelemetry"
apple-notes search "TODO|FIXME" --regex
apple-notes search "invoice" --folder Finance --since 1w
apple-notes search "postgres" --json | jq -r '.[].title'
apple-notes search "draft" --body-only --no-snippets

Results rank by match count, then by recency. Titles are searched alongside bodies unless you pass --body-only. --json emits structured records, which is the useful shape for piping into an LLM or another tool.

recent

apple-notes recent -n 50
apple-notes recent --since 6h --folder Work

Metadata only — bodies are never inflated, so this stays fast regardless of store size.

export

apple-notes export ~/Downloads/notes
apple-notes export ~/Downloads/notes --incremental

One Markdown file per note, mirroring your folder tree, with YAML frontmatter (title, ids, dates, folder, links, attachments, and a notes:// link back to the note). Attachments are copied next to the Markdown under attachments/<id>/. --incremental keeps a manifest so unchanged notes are skipped and exports of deleted notes are pruned.

How it works

NoteStore.sqlite
  └── ZICNOTEDATA.ZDATA         gzip → protobuf → text runs → Markdown
  └── ZICCLOUDSYNCINGOBJECT     titles, dates, folder tree, attachments

Module	Role
store.py	read-only SQLite access, folder tree, attachments
parser.py	gzip + protobuf decoding, Markdown rendering
search.py	search, recency listing, single-note reads
export.py	Markdown output and the incremental manifest

Three details are worth knowing if you build something similar:

Open the database with mode=ro, never immutable=1. The immutable flag makes SQLite skip the -wal file, which silently serves a stale snapshot missing your most recent notes. On a live store the -wal file routinely holds megabytes of un-checkpointed data. WAL mode allows concurrent readers, so mode=ro is safe while Notes.app is running and never blocks it. Export uses SQLite's backup() API instead, for a stable point-in-time copy.

There is no FTS index. The schema has no full-text tables, and bodies are gzipped protobuf blobs, so WHERE body LIKE … is not available. Search means inflating every candidate body and matching in memory. At ~800 notes that is about 30 ms, so this tool does no caching and always reflects the live store.

Recently Deleted is ZFOLDERTYPE = 1. Notes in the trash keep ZMARKEDFORDELETION = 0, so filtering on that column alone still surfaces them. Matching on the folder type is also language-independent, unlike comparing against a localized "Recently Deleted" string. They are excluded by default; pass --include-trashed to include them.

Exit codes

search follows the grep convention: 0 when something matched, 1 when nothing did, 2 on a bad argument or an unreadable database. That makes it usable in a conditional:

if apple-notes search "release checklist" --no-snippets >/dev/null; then
  echo "found it"
fi

Reading is all it does

This tool only reads. It never writes to NoteStore.sqlite — modifying the store directly would corrupt CloudKit's sync state and risk losing notes. If you need to create or edit notes, drive Notes.app through AppleScript for the write path and use this for reading.

Password-protected notes are listed but their bodies stay encrypted and unreadable; they are skipped unless you pass --include-password-protected.

Development

uv run python -m unittest discover -s tests

tests/test_parity.py is the original single-file exporter's suite, kept unchanged apart from neutralized example URLs, so it guards the protobuf decoding against regressions. tests/test_search.py builds a synthetic Core Data store to cover the query layer, trash handling, and time filters.

License

MIT