Experimental. Shouldn't be considered production ready yet.

nanotes

A standalone CLI for reading and creating notes in Apple Notes.

Uses JXA (JavaScript for Automation) for list/search/create and direct SQLite + protobuf access for low-level operations (dump).

Human-readable text output by default; pass --json for structured JSON.

Install

./install.sh

This creates ~/bin/nanotes. Make sure ~/bin is in your PATH.

Requires Deno 2+.

Permissions (macOS)

Grant Automation access for your terminal to control Notes.app:

• System Settings > Privacy & Security > Automation
• Enable your terminal app -> Notes

If the toggle does not appear, run nanotes folders once and allow the system prompt.

Full Disk Access is required for dump (reads NoteStore.sqlite directly).

Commands

folders

List all folders with account name and note count.

nanotes folders
nanotes folders --json

list

List notes sorted by modification date (newest first).

nanotes list
nanotes list --folder "Work" --limit 10
nanotes list --json

recent

Show notes modified recently. Default window is 3 days.

nanotes recent
nanotes recent --since 24h
nanotes recent --since 1w --folder "Work"
nanotes recent --content               # include note bodies
nanotes recent --json

today

Show notes modified today (since midnight).

nanotes today
nanotes today --content
nanotes today --json

show

Show full note content. Default output is plaintext.

nanotes show --id "x-coredata://UUID/ICNote/p1234"
nanotes show --id "x-coredata://UUID/ICNote/p1234" --json
nanotes show --id "x-coredata://UUID/ICNote/p1234" --json --html

--html returns the raw HTML body instead of plaintext. Only meaningful with --json.

search

Search notes by title (case-insensitive).

nanotes search "Shopping"
nanotes search "recipe" --folder "Cooking" --limit 5
nanotes search "recipe" --json

attachments

List attachments on a note.

nanotes attachments --id "x-coredata://UUID/ICNote/p1234"
nanotes attachments --id "x-coredata://UUID/ICNote/p1234" --json

dump

Full lossless JSON dump of a note: decoded protobuf, metadata, and attachment info. Always outputs JSON.

nanotes dump --id "x-coredata://UUID/ICNote/p1234"

create

Create a new note. --title is required.

nanotes create --title "Meeting Notes" --body "Discussion points..."
nanotes create --title "Ideas" --folder "Work" --json

Global Options

| Flag | Description | |------|-------------| | --json | Output JSON instead of human-readable text |

JSON Shapes

folders

[
  {
    "name": "Notes",
    "id": "x-coredata://UUID/ICFolder/p1",
    "container": "iCloud",
    "noteCount": 42
  }
]

list / search / recent / today

[
  {
    "id": "x-coredata://UUID/ICNote/p1234",
    "title": "Shopping List",
    "folder": "Notes",
    "created": "2026-03-04T10:30:00.000Z",
    "modified": "2026-03-04T14:15:00.000Z"
  }
]

show

{
  "id": "x-coredata://UUID/ICNote/p1234",
  "title": "Shopping List",
  "folder": "Notes",
  "created": "2026-03-04T10:30:00.000Z",
  "modified": "2026-03-04T14:15:00.000Z",
  "passwordProtected": false,
  "body": "Milk\nEggs\nBread"
}

attachments

[
  {
    "name": "photo.jpg",
    "id": "x-coredata://UUID/ICAttachment/p5678",
    "contentIdentifier": "ABC123"
  }
]

create

{
  "id": "x-coredata://UUID/ICNote/p9999",
  "title": "New Note",
  "folder": "Notes",
  "created": "2026-03-04T16:00:00.000Z"
}

Internals

See NOTES-INTERNALS.md for documentation of the Apple Notes storage format, protobuf schema, CRDT entries, and sync procedure.

Testing

See TEST.md for integration test instructions.

Skill Install

To use as a Claude Code skill:

cd ~/.claude/skills
git clone https://github.com/shareup/nanotes.git

Development

deno task check   # Type-check
deno task test    # Run protobuf round-trip tests
deno task run -- folders

License

MIT