MacNotesApp

The macnotesapp library provides a Python interface to Apple's Notes.app. The primary entry point is the NotesApp class, which manages the connection to the application. Other key classes include:

• NotesApp: The main interface to Notes.app.
• Account: Represents a specific Notes account (e.g., iCloud, On My Mac).
• Folder: Represents a folder within a specific account.
• Note: Represents an individual note.
• NotesList: A collection of notes.
• Attachment: Represents files attached to a note.

To use the MacNotesApp command line interface (CLI) without manually managing Python virtual environments, install it using pipx. This installs the notes executable directly to your path.

Prerequisites

Ensure you have Homebrew installed on your macOS system.

Installation Steps

1. Install pipx using Homebrew:

   brew install pipx

2. Install macnotesapp using pipx:

   pipx install macnotesapp

3. Verify the installation by running the notes command:

   notes

The recommended installation method is via the uv Python package manager.

1. Install uv using the official script:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install macnotesapp with Python 3.13:

uv tool install --python 3.13 macnotesapp

To upgrade the tool later, use:

uv tool upgrade macnotesapp

You can also run the tool without installing it using uv tool run --python 3.13 macnotesapp or uvx --python 3.13 macnotesapp.

MacNotesApp uses uv for dependency management. To set up a local development environment, synchronize the dependencies to create a virtual environment in .venv/.

To execute commands within the environment, prefix them with uv run or activate the environment manually.

# Create virtual environment and install dependencies
uv sync

# Run commands via uv
uv run notes --help

# Or activate manually
source .venv/bin/activate

If you installed macnotesapp via pipx, you can upgrade to the latest version by running:

pipx upgrade macnotesapp

The test suite uses pytest. Warning: The tests are interactive and operate on your actual Notes.app data. Because they require user input, you must use the -s flag to prevent pytest from capturing stdout/stderr.

uv run pytest -v -s tests/

For users on Apple Silicon (M1, etc.) Macs, you can install the CLI via Homebrew:

1. Tap the repository:

brew tap RhetTbull/macnotesapp https://github.com/RhetTbull/macnotesapp

2. Update and install:

brew update
brew install macnotesapp

After installation, the command is invoked using notes.

Note: This method is not supported on Intel Macs; use the uv method instead.

To package the project for distribution, use the provided build script. To publish to PyPI, use uv build followed by uv publish.

# Build the project
./build.sh

# Publish to PyPI
uv build
uv publish

Documentation is maintained in the docs/ directory using mkdocs. You can build the documentation locally or deploy it directly to GitHub Pages.

# Build documentation locally
uv run mkdocs build

# Deploy documentation to GitHub Pages
uv run mkdocs gh-deploy

The macnotesapp package exports several core classes to model the hierarchy of Apple Notes:

• Account: Represents a specific Notes account (e.g., iCloud, On My Mac).
• Folder: Represents a folder within a specific account.
• Note: Represents an individual note containing content and metadata.
• NotesList: A collection of notes, typically returned by queries or account/folder lookups.

The rich_click_echo function is a specialized wrapper around click.echo. It is designed to capture rich-formatted output (including Markdown and colors) into a buffer and then pass that buffer to click.echo.

This ensures that even when using click's standard output mechanisms, the visual richness provided by the rich library is preserved. It automatically handles terminal width detection to prevent unwanted wrapping during tests or when outputting to non-terminal environments.