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-foldersOutput format: account → folder (one per line).
Create a note
echo '<json>' | "$SKILL_DIR/scripts/notes.sh" create-noteJSON 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-noteJSON 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-notesJSON 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-notesJSON 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-foldersThen:
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-noteCritical 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.logwith timestamp, command, and note title - Body uses plain text — newlines in
bodyare converted to<br>automatically; usehtmlfor rich formatting - Note title = first line — Notes.app treats the first line of the body as the note name