apple-notes-exporter

Apple Notes Exporter

A TypeScript library and CLI for exporting Apple Notes folders to HTML files via AppleScript.

Quick Start

# List all your Notes folders
npx apple-notes-exporter list

# Export a folder to HTML files
npx apple-notes-exporter export "My Notes" ./output

Features

• Export Apple Notes folders recursively to HTML files
• Preserve folder hierarchy in the exported directory structure
• Support for multiple accounts (iCloud, Google, On My Mac, etc.)
• Both async and sync APIs
• TypeScript types included

Requirements

• macOS only - This tool relies on AppleScript and the Notes app
• Node.js 18+
• Automation permissions for Notes app (System Settings > Privacy & Security > Automation)

Installation

npm install apple-notes-exporter
# or
pnpm add apple-notes-exporter
# or
yarn add apple-notes-exporter

CLI Usage

List all folders

apple-notes-exporter list
# or
apple-notes-exporter ls

Output:

=== Available Top-Level Folders ===
iCloud > Notes
iCloud > Work
Google > Notes
====================================

Export a folder

# Export a folder (searches all accounts)
apple-notes-exporter export "My Notes" ./output

# Export from a specific account (use when folder names are duplicated)
apple-notes-exporter export "iCloud:Work" ./output
apple-notes-exporter export "Google:Notes" ./google-notes

Help

apple-notes-exporter help
apple-notes-exporter --help

Library Usage

Quick Start

import { listFolders, exportFolder, exportFolderFromAccount } from 'apple-notes-exporter';

// List all available folders
await listFolders();

// Export a folder to a directory (searches all accounts)
await exportFolder('My Notes', './exports');

// Export from a specific account (useful when folder names are duplicated)
await exportFolderFromAccount('iCloud', 'Work', './exports');
await exportFolderFromAccount('Google', 'Notes', './google-exports');

Using the Exporter Class

For more control, use the Exporter class directly:

import { Exporter } from 'apple-notes-exporter';

// Create an exporter with the default vendored script
const exporter = Exporter.create();

await exporter.listFolders();
await exporter.exportFolder('My Notes', './exports');
await exporter.exportFolderFromAccount('iCloud', 'Work', './exports');

Using a Custom AppleScript

import { Exporter } from 'apple-notes-exporter';

const exporter = Exporter.withScriptPath('./my-custom-script.applescript');
await exporter.exportFolder('My Notes', './exports');

Synchronous API

All methods have synchronous versions:

import { listFoldersSync, exportFolderSync, exportFolderFromAccountSync } from 'apple-notes-exporter';

listFoldersSync();
exportFolderSync('My Notes', './exports');
exportFolderFromAccountSync('iCloud', 'Work', './exports');

Error Handling

import {
  exportFolder,
  ExportError,
  UnsupportedPlatformError,
  ScriptNotFoundError,
  ScriptFailedError
} from 'apple-notes-exporter';

try {
  await exportFolder('My Notes', './exports');
} catch (error) {
  if (error instanceof UnsupportedPlatformError) {
    console.error('This tool only works on macOS');
  } else if (error instanceof ScriptNotFoundError) {
    console.error('AppleScript not found:', error.scriptPath);
  } else if (error instanceof ScriptFailedError) {
    console.error('Export failed with exit code:', error.exitCode);
  } else if (error instanceof ExportError) {
    console.error('Export error:', error.message);
  } else {
    throw error;
  }
}

API Reference

Convenience Functions

Function	Description
listFolders()	List all top-level folders across all accounts
exportFolder(folder, outputDir)	Export a folder recursively (searches all accounts)
exportFolderFromAccount(account, folder, outputDir)	Export a folder from a specific account

All functions have *Sync variants for synchronous execution.

Exporter Class

Method	Description
Exporter.create()	Create an exporter with the vendored AppleScript
Exporter.withScriptPath(path)	Create an exporter with a custom AppleScript
exporter.listFolders()	List all top-level folders
exporter.exportFolder(folder, outputDir)	Export a folder recursively
exporter.exportFolderFromAccount(account, folder, outputDir)	Export from a specific account

Error Types

Error	Description
ExportError	Base class for all export errors
UnsupportedPlatformError	Thrown when not running on macOS
ScriptNotFoundError	Thrown when the AppleScript file is not found
TempFileError	Thrown when temp file creation fails
InvalidPathError	Thrown when the output path is invalid
LaunchError	Thrown when osascript fails to launch
ScriptFailedError	Thrown when the AppleScript exits with non-zero status

Output Format

Exported notes are saved as HTML files with the format:

{output_dir}/
  {folder_name}/
    {note_title} -- {id}.html
    {subfolder_name}/
      {note_title} -- {id}.html
      ...

The id suffix ensures unique filenames when notes have the same title.

Permissions

On first run, macOS will prompt you to grant automation permissions. You can also configure this manually:

• Open System Settings
• Go to Privacy & Security > Automation
• Enable Notes access for Terminal (or your application)

Example Output

Each note is exported as an HTML fragment (not a full HTML document). The output starts directly with <div> tags containing the note's rich text content:

<div><h1>My Note Title</h1></div>
<div><br></div>
<div>This is the content of my note with <b>formatting</b> preserved.</div>
<div><br></div>
<div>
  <ul>
    <li>Bullet points work</li>
    <li>So do checklists</li>
  </ul>
</div>

Note: There is no <html>, <head>, or <body> wrapper. This is the raw HTML body content as returned by the Notes app. If you need a full HTML document, you'll need to wrap the content yourself.

Troubleshooting

"Notes is not allowed to be automated"

You need to grant automation permissions:

• Open System Settings > Privacy & Security > Automation
• Find your terminal app (Terminal, iTerm, VS Code, etc.)
• Enable the toggle for Notes

"No folders found"

• Ensure you have at least one folder in the Notes app
• Check that Notes is not in a broken state (try opening Notes manually)
• Verify automation permissions are granted

Notes app keeps opening/closing

This is normal behavior. The AppleScript needs to communicate with Notes, which may briefly activate the app.

Export is slow

Large folders with many notes take time to export. The script processes notes sequentially to avoid overwhelming the Notes app.

"Could not find folder named: X"

• Check the exact folder name (case-sensitive)
• Use apple-notes-exporter list to see available folders
• If the folder is in a specific account, use the Account:Folder format

Related Projects

• apple-notes-exporter-rs - Rust implementation of this tool
• apple-notes-exporter - The underlying AppleScript

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Development Setup

# Clone with submodules
git clone --recurse-submodules https://github.com/pRizz/apple-notes-exporter-ts.git
cd apple-notes-exporter-ts

# Install dependencies
pnpm install

# Build
pnpm build

# Run locally
node dist/cli.js list

License

MIT