Apple Notes Install & Auth

Overview

Apple Notes has no REST API. Automation uses macOS scripting technologies: AppleScript, JavaScript for Automation (JXA), Shortcuts, and the osascript command-line tool. No SDK to install — but you need macOS accessibility permissions.

Prerequisites

• macOS 13+ (Ventura or later recommended)
• Terminal app or iTerm2
• System Preferences > Privacy & Security > Automation permissions

Instructions

Step 1: Grant Automation Permissions

# macOS requires explicit permission for scripts to control Notes.app
# The first time you run an osascript command targeting Notes, macOS will prompt.
# You can also pre-grant in: System Preferences > Privacy & Security > Automation

# Test basic Notes access (will trigger permission prompt)
osascript -e 'tell application "Notes" to get name of every note in default account'

Step 2: Verify JXA (JavaScript for Automation) Access

# JXA is the modern alternative to AppleScript
# Run JavaScript via osascript with -l JavaScript flag

osascript -l JavaScript -e '
  const Notes = Application("Notes");
  Notes.includeStandardAdditions = true;
  const noteCount = Notes.defaultAccount.notes.length;
  `Apple Notes accessible: ${noteCount} notes found`;
'

Step 3: Create a Wrapper Script

#!/bin/bash
# scripts/notes-cli.sh — Wrapper for common Apple Notes operations

case "$1" in
  count)
    osascript -l JavaScript -e '
      const Notes = Application("Notes");
      Notes.defaultAccount.notes.length;
    '
    ;;
  list)
    osascript -l JavaScript -e '
      const Notes = Application("Notes");
      const notes = Notes.defaultAccount.notes();
      notes.slice(0, 20).map(n => `${n.id()} | ${n.name()}`).join("\n");
    '
    ;;
  folders)
    osascript -l JavaScript -e '
      const Notes = Application("Notes");
      Notes.defaultAccount.folders().map(f => f.name()).join("\n");
    '
    ;;
  *)
    echo "Usage: notes-cli.sh {count|list|folders}"
    ;;
esac

Step 4: Verify Shortcuts Integration

# Apple Shortcuts can also interact with Notes
# Check available shortcuts
shortcuts list | grep -i note

# Run a shortcut that creates a note
shortcuts run "Create Note" --input-path /dev/stdin <<< "Test content"

Automation Technologies

Technology	Language	Best For	Docs
AppleScript	AppleScript	Simple operations	Apple Scripting Guide
JXA	JavaScript	Complex logic, JSON handling	Apple JXA Reference
osascript	CLI wrapper	Scripts, CI/CD	man osascript
Shortcuts	Visual	Non-developer workflows	Shortcuts app
PyXA	Python	Python automation	pyxa.dev

Output

• A recorded consent decision for the exact invoking app and macOS user
• A read-only, scoped authorization result (not a complete note listing)
• A wrapper that exposes only the approved operations and fails on unknown input
• An explicit decision on whether any Shortcuts workflow is approved

Examples

For a first-time setup, run one read-only count against the intended account and accept the macOS prompt in the interactive session. Do not use the list wrapper against a production account unless the task specifically requires metadata discovery; it can expose titles in terminal history and CI logs. For Shortcuts, use a non-production shortcut and a test note rather than a workflow that creates notes in a default account.

Error Handling

Error	Cause	Solution
Not authorized to send Apple events	Missing automation permission	Grant in System Preferences > Privacy > Automation
Notes got an error: AppleEvent timed out	Notes.app not running	Launch Notes first or add activate
-1743 errAEAppNotAllowed	Denied by TCC	Reset TCC: tccutil reset AppleEvents
execution error: Notes is not running	Notes.app closed	Add tell app "Notes" to activate

Resources

• Mac Automation Scripting Guide
• JXA Reference
• AppleScript Notes Dictionary

Next Steps

Proceed to apple-notes-hello-world for your first note creation.