Apple Notes Exporter


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

Quick Start

``bash


List all your Notes folders

`bash
npm install apple-notes-exporter


or

`bash
apple-notes-exporter list


or

Output:
`
=== Available Top-Level Folders ===
iCloud > Notes
iCloud > Work
Google > Notes
====================================
`

$3

`bash


Export a folder (searches all accounts)

`bash
apple-notes-exporter help
apple-notes-exporter --help
`

Library Usage

$3

`typescript
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');
`

$3

For more control, use the Exporter class directly:

`typescript
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');
`

$3

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

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

$3

All methods have synchronous versions:

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

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

$3

`typescript
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

$3

| 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.

$3

| 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 |

$3

| 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:

1. Open System Settings
2. Go to Privacy & Security > Automation
3. 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