Apple Notes CLI Integration

A command-line interface for Apple Notes that enables quick note capture and retrieval from the terminal. Uses AppleScript to safely interact with Notes.app, with a Claude Code skill wrapper for natural language interaction.

Built for Claude Code - This integration works seamlessly with Claude Code for natural language note management.

Overview

This integration provides:

• AppleScript backend - Safe interaction with Notes.app API
• Node.js CLI - Clean command-line interface
• Forked skill - Natural language wrapper for conversational use
• Plain text support - v1 focuses on plain text notes

Installation

For Claude Code Users

1. Clone the repository:

   git clone https://github.com/keithlang/apple-notes-cli.git ~/.claude/skills/apple-notes

2. Make the CLI executable:

   chmod +x ~/.claude/skills/apple-notes/cli.js

3. You're done! The skill will be automatically available in Claude Code.

For CLI-Only Users

If you just want the command-line tool without Claude Code integration:

git clone https://github.com/keithlang/apple-notes-cli.git
cd apple-notes-cli
chmod +x cli.js

Optionally add to your PATH or create an alias.

File Structure

~/.claude/skills/apple-notes/
├── cli.js                      # Node.js CLI
├── scripts/
│   ├── create-note.applescript # Create notes
│   ├── read-note.applescript   # Read notes
│   └── list-notes.applescript  # List notes
├── SKILL.md                    # Forked skill wrapper
├── package.json
└── README.md                   # This file

Permissions

On first use, macOS will prompt you to grant permissions:

1. Terminal/Claude Access to Notes:

   • When you first run a command, you'll see a system dialog
   • Click "OK" to allow access
   • If denied, go to: System Settings > Privacy & Security > Automation
   • Enable "Notes" for Terminal or Claude

2. Troubleshooting Permissions:

   • If commands fail with "Not authorized", check System Settings
   • You may need to remove and re-add permissions
   • Restart Terminal/Claude after changing permissions

CLI Usage

Create a Note

~/.claude/skills/apple-notes/cli.js create "Note Title" "Note body content"

Example:

~/.claude/skills/apple-notes/cli.js create "Meeting Notes" "Discussed Q1 goals
Action items:
- Alice: Draft proposal
- Bob: Schedule follow-up"

Read a Note

~/.claude/skills/apple-notes/cli.js read "Note Title"

Example:

~/.claude/skills/apple-notes/cli.js read "Meeting Notes"

List All Notes

~/.claude/skills/apple-notes/cli.js list

Help

~/.claude/skills/apple-notes/cli.js --help

Skill Usage

The skill wrapper (apple-notes) allows natural language interaction through Claude Code:

Create:

• "Create a note called Shopping List with bread, milk, eggs"
• "Make a note titled Meeting Notes with discussion points"
• "New note: Project Ideas - build an app for task management"

Read:

• "Show me my Shopping List note"
• "Read the note called Meeting Notes"
• "What's in my Project Ideas note?"

List:

• "List all my notes"
• "Show me all notes"
• "What notes do I have?"

Examples

Example 1: Quick Meeting Notes

~/.claude/skills/apple-notes/cli.js create "Team Meeting 2024-02-09" "Attendees: Alice, Bob
Topics:
- Q1 goals
- New project kickoff

Action items:
- Alice: Draft proposal by Friday
- Bob: Schedule follow-up"

Example 2: Reading Back Notes

~/.claude/skills/apple-notes/cli.js read "Team Meeting 2024-02-09"

Output:

Team Meeting 2024-02-09
Attendees: Alice, Bob
Topics:
- Q1 goals
- New project kickoff

Action items:
- Alice: Draft proposal by Friday
- Bob: Schedule follow-up

Example 3: Finding All Notes

~/.claude/skills/apple-notes/cli.js list

Technical Details

• AppleScript Backend: Uses osascript to interact with Notes.app API
• Node.js CLI: Wraps AppleScript for easy command-line access
• Forked Skill: Natural language wrapper for conversational use
• Plain Text Only: v1 supports plain text (no HTML/formatting)
• Exact Title Match: Read command requires exact title match
• Duplicate Handling: Creating notes with existing titles creates duplicates (Notes.app behavior)
• iCloud Sync: Notes sync automatically if you have iCloud Notes enabled

Troubleshooting

"Command not found: osascript"

• osascript is built into macOS
• Ensure you're running on macOS

"Not authorized to send Apple events"

• Grant permissions in System Settings > Privacy & Security > Automation
• Enable "Notes" for Terminal/Claude
• Restart your terminal

"Note not found"

• Check exact title (case-sensitive)
• Use cli.js list to see available notes
• Remember: exact match required

Special characters in titles/body

• Use quotes around arguments
• Quotes inside strings are handled automatically
• Newlines are preserved in note bodies

Script path errors

• Ensure scripts/ directory exists with .applescript files
• Run from ~/.claude/skills/apple-notes/ directory or use full path

Limitations (v1)

• ✗ No folder organization support
• ✗ No HTML/rich text formatting
• ✗ No note editing (only create/read)
• ✗ No note deletion
• ✗ No fuzzy search (exact title match only)
• ✗ No date filtering
• ✗ No attachments

Future versions may add these features.

Development

Project Structure

~/.claude/skills/apple-notes/
├── cli.js                      # Node.js CLI
├── scripts/
│   ├── create-note.applescript # AppleScript for creating
│   ├── read-note.applescript   # AppleScript for reading
│   └── list-notes.applescript  # AppleScript for listing
├── SKILL.md                    # Forked skill definition
├── package.json                # Node.js package config
└── README.md                   # This file

Testing

Manual testing is required for each component:

1. Test AppleScripts directly:

   osascript scripts/create-note.applescript "Test" "Body"
   osascript scripts/read-note.applescript "Test"
   osascript scripts/list-notes.applescript

2. Test CLI commands:

   ./cli.js create "Test" "Body"
   ./cli.js read "Test"
   ./cli.js list

3. Test skill wrapper:

   • Use natural language with Claude
   • Try various phrasings
   • Test error cases (note not found, etc.)

Adding Features

To add new features (e.g., delete, edit, search):

1. Create new AppleScript in scripts/
2. Add command handler in cli.js
3. Update SKILL.md with new capabilities
4. Update this README with examples

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Future Enhancements (v2+)

• Folder/organization support
• HTML/rich text formatting
• Note editing and updating
• Note deletion
• Fuzzy search
• Date filtering
• Attachment support

Related

• AppleScript Notes Documentation
• Claude Code

License

MIT