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:

Read a note

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

JSON fields:

List notes

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

JSON fields:

Search notes

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

JSON fields:

Interpreting natural language

Map user requests to commands:

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
automatically; use html for rich formatting
8. Note title = first line — Notes.app treats the first line of the body as the note name