macos-notes

macOS Notes

Manage Apple Notes via $SKILL_DIR/scripts/notes.sh. Notes content is stored as HTML internally; the script accepts plain text or HTML body and returns plaintext when reading.

Quick start

List folders

Always list folders first to discover accounts and folder names:

"$SKILL_DIR/scripts/notes.sh" list-folders

Output format: account → folder (one per line).

Create a note

echo '<json>' | "$SKILL_DIR/scripts/notes.sh" create-note

JSON fields:

Field	Required	Default	Description
title	yes	-	Note title (becomes the first line / heading)
body	no	""	Note content (plain text — converted to HTML automatically)
html	no	""	Raw HTML body (overrides body if both provided)
folder	no	default folder	Folder name (from list-folders)
account	no	default account	Account name (from list-folders)

Read a note

echo '<json>' | "$SKILL_DIR/scripts/notes.sh" read-note

JSON fields:

Field	Required	Default	Description
name	yes	-	Note title (exact match)
folder	no	all folders	Folder to search in
account	no	default account	Account to search in

List notes

echo '<json>' | "$SKILL_DIR/scripts/notes.sh" list-notes

JSON fields:

Field	Required	Default	Description
folder	no	default folder	Folder name
account	no	default account	Account name
limit	no	20	Max notes to return

Search notes

echo '<json>' | "$SKILL_DIR/scripts/notes.sh" search-notes

JSON fields:

Field	Required	Default	Description
query	yes	-	Text to search for in note titles
account	no	default account	Account to search in
limit	no	10	Max results to return

Interpreting natural language

Map user requests to commands:

User says	Command	Key fields
"Note this down: ..."	create-note	title, body
"Save meeting notes"	create-note	title: "Meeting notes — <date>", body
"What did I write about X?"	search-notes	query: "X"
"Show my notes"	list-notes	(defaults)
"Read my note about X"	read-note	name: "X"
"Save this in my work notes"	create-note	Match closest account/folder from list-folders

Example prompts

"Note down the API key format: prefix_xxxx"

echo '{"title":"API key format","body":"Format: prefix_xxxx"}' | "$SKILL_DIR/scripts/notes.sh" create-note

"Show my recent notes"

echo '{}' | "$SKILL_DIR/scripts/notes.sh" list-notes

"What did I write about passwords?"

echo '{"query":"password"}' | "$SKILL_DIR/scripts/notes.sh" search-notes

"Read my note about Hinge"

echo '{"name":"Hinge"}' | "$SKILL_DIR/scripts/notes.sh" read-note

"Create a meeting summary in my iCloud notes"

"$SKILL_DIR/scripts/notes.sh" list-folders

Then:

echo '{"title":"Meeting summary — 2026-02-17","body":"Discussed roadmap.\n- Q1: launch MVP\n- Q2: iterate","account":"iCloud","folder":"Notes"}' | "$SKILL_DIR/scripts/notes.sh" create-note

Critical rules

1. Always list folders first if the user hasn't specified an account/folder — folder names are reused across accounts
2. Specify both account and folder when targeting a specific location — folder: "Notes" alone is ambiguous
3. Password-protected notes are skipped — the script cannot read or modify them
4. Pass JSON via stdin — never as a CLI argument (avoids leaking data in process list)
5. All fields are validated by the script (type coercion, range checks) — invalid input is rejected with an error
6. All actions are logged to logs/notes.log with timestamp, command, and note title
7. Body uses plain text — newlines in body are converted to <br> automatically; use html for rich formatting
8. Note title = first line — Notes.app treats the first line of the body as the note name