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