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:

bash

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

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

Create a note

bash

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

bash

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

bash

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

bash

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"

bash

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

"Show my recent notes"

bash

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

"What did I write about passwords?"

bash

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

"Read my note about Hinge"

bash

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

"Create a meeting summary in my iCloud notes"

bash

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

Then:

bash

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

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