### Install MacNotesApp with Pipx
Source: https://rhettbull.github.io/macnotesapp
Use this command to install the macnotesapp CLI tool via pipx. Pipx manages virtual environments, simplifying installation.
```bash
pipx install macnotesapp
```
--------------------------------
### Get help for notes commands
Source: https://rhettbull.github.io/macnotesapp/cli
Use the 'notes help' command to display help information. You can specify a topic or subtopic for more specific help, such as 'help add'.
```bash
notes help [OPTIONS] [TOPIC] [SUBTOPIC]
```
```bash
--help Show this message and exit.
```
--------------------------------
### Get Folder Name
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves the name of the folder as a string.
```python
@property
def name(self) -> str:
"""Name of folder"""
return str(self._folder.name())
```
--------------------------------
### Get Notes App Version
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the version string of the Notes.app. This can be helpful for compatibility checks or logging.
```python
version = notes_app.version
```
--------------------------------
### Get Account Folders
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a list of folder names within the Notes.app account. It first attempts to get folder objects and then their names, falling back to a script if necessary.
```python
@property
def folders(self) -> list[str]:
"""Return list of folder names in account"""
if folders := self._account.folders():
return [str(f.name()) for f in folders]
return [str(f) for f in self._run_script("accountGetFolderNames")]
```
--------------------------------
### Upgrade MacNotesApp with Pipx
Source: https://rhettbull.github.io/macnotesapp
To upgrade to the latest version of macnotesapp after initial installation with pipx, use the upgrade command.
```bash
pipx upgrade macnotesapp
```
--------------------------------
### Get Notes App Instance
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the underlying SBApplication object for Notes.app. This can be useful for advanced scripting or direct interaction with AppleScriptable properties.
```python
app = notes_app.app
```
--------------------------------
### Get Folder Object
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a Folder object for a specified folder name.
```python
def folder(self, folder: str) -> "Folder":
"""Return Folder object for folder with name folder."""
folder_obj = self._folder_for_name(folder)
return Folder(folder_obj)
```
--------------------------------
### Get Notes by Filter - Python
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a list of Note objects, optionally filtered by name, body, text, password protection status, ID, or account. Use this to get individual note details.
```python
def notes(
self,
name: list[str] | None = None,
body: list[str] | None = None,
text: list[str] | None = None,
password_protected: bool | None = None,
id: list[str] | None = None,
accounts: list[str] | None = None,
) -> list["Note"]:
"""Return Note object for all notes contained in Notes.app or notes filtered by property.
Args:
name: list of note names to filter by
body: list of note bodies to filter by
text: list of note text to filter by
password_protected: filter by password protected notes
id: list of note ids to filter by
accounts: list of account names to filter by
Returns:
list of Note objects
"""
# TODO: should this be a generator?
account_list = self.app.accounts()
if accounts:
format_str = "name == %@" + " OR name == %@ " * (len(accounts) - 1)
predicate = AppKit.NSPredicate.predicateWithFormat_(format_str, accounts)
account_list = account_list.filteredArrayUsingPredicate_(predicate)
notes = []
for account in account_list:
notes.extend(
Account(account).notes(name, body, text, password_protected, id)
)
return notes
```
--------------------------------
### Get Note as Dictionary
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a dictionary representation of the note object, including its metadata and content.
```python
def asdict(self) -> dict[str, Any]:
"""Return dict representation of note"""
return {
"account": self.account,
"id": self.id,
"name": self.name,
"body": self.body,
"plaintext": self.plaintext,
"creation_date": self.creation_date,
"modification_date": self.modification_date,
"password_protected": self.password_protected,
"folder": self.folder,
}
```
--------------------------------
### Get Note Count
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total number of notes within the account.
```python
def __len__(self) -> int:
"""Return count of notes"""
return len(self._account.notes())
```
--------------------------------
### Get Note Count
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total number of notes within the account.
```python
def __len__(self) -> int:
"""Return count of notes"""
return len(self._account.notes())
```
--------------------------------
### Convert Note to List of Dictionaries
Source: https://rhettbull.github.io/macnotesapp/reference
Use this method to get a list of dictionaries, where each dictionary represents a note with its attributes. It iterates through various note properties using zip.
```python
def asdict(self) -> list[dict[str, str]]:
"""Return list of dict representations of note"""
return [
{
"id": note[0],
"name": note[1],
"body": note[2],
"plaintext": note[3],
"creation_date": note[4],
"modification_date": note[5],
"password_protected": note[6],
"folder": note[7],
}
for note in zip(
self.id,
self.name,
self.body,
self.plaintext,
self.creation_date,
self.modification_date,
self.password_protected,
self.container,
)
]
```
--------------------------------
### Get Folder Object
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a Folder object for a given folder name. This is a convenience method for accessing specific folders.
```python
def folder(self, folder: str) -> "Folder":
"""Return Folder object for folder with name folder."""
folder_obj = self._folder_for_name(folder)
return Folder(folder_obj)
```
--------------------------------
### Get Default Account
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the name of the default account set in Notes.app. New notes are typically created in this account if not otherwise specified.
```python
default_account = notes_app.default_account
```
--------------------------------
### Get Account Name
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves the name of the Notes.app account. This property provides a string representation of the account's name.
```python
@property
def name(self) -> str:
"""Return name of account"""
return str(self._account.name())
```
--------------------------------
### Get Total Note Count
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total number of notes across all accounts in the Notes application. It sums the counts from each account.
```python
def __len__(self) -> int:
"""Return count of notes in Notes.app"""
return sum(len(account.notes()) for account in self.app.accounts())
```
--------------------------------
### Get Account Object by Name
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves an Account object based on its name. If no account name is provided, it defaults to the application's default account. Raises a ValueError if the specified account cannot be found.
```python
account = account or self.default_account
predicate = AppKit.NSPredicate.predicateWithFormat_("name == %@", account)
accounts = self.app.accounts().filteredArrayUsingPredicate_(predicate)
if not accounts:
raise ValueError(f"Could not find account {account}")
account_obj = accounts[0]
return Account(account_obj)
```
--------------------------------
### Get Specific Account Object
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves an Account object for a specified account name. If no name is provided, it returns the default account. Raises ValueError if the account is not found.
```python
def account(self, account: Optional[str] = None) -> "Account":
"""Return Account object for account or default account if account is None.
Arg:
account: name of account to return. If None, return default account.
Returns:
Account object
"""
account = account or self.default_account
predicate = AppKit.NSPredicate.predicateWithFormat_("name == %@", account)
accounts = self.app.accounts().filteredArrayUsingPredicate_(predicate)
if not accounts:
raise ValueError(f"Could not find account {account}")
account_obj = accounts[0]
return Account(account_obj)
```
--------------------------------
### Get Total Number of Notes
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total count of notes across all accounts in the Notes application. It iterates through each account and sums the number of notes.
```python
return sum(len(account.notes()) for account in self.app.accounts())
```
--------------------------------
### Get Notes with Filtering - Python
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves notes, optionally filtering by name, body, text, password protection status, or ID. Uses NSPredicate for complex filtering.
```python
def notes(
self,
name: list[str] | None = None,
body: list[str] | None = None,
text: list[str] | None = None,
password_protected: bool | None = None,
id: list[str] | None = None,
) -> list["Note"]:
"""Return Note object for all notes contained in account or notes filtered by property.
Args:
name: list of note names to filter by
body: list of note bodies to filter by
text: list of note text to filter by
password_protected: filter by password protected notes
id: list of note ids to filter by
Returns:
list of Note objects
"""
# TODO: should this be a generator?
notes = self._account.notes()
format_strings = []
if name and notes:
name_strings = ["(name contains[cd] %@)"] * len(name)
format_strings.append(name_strings)
if body and notes:
body_strings = ["(plaintext contains[cd] %@)"] * len(body)
format_strings.append(body_strings)
if text and notes:
text_strings = ["(name contains[cd] %@)"] * len(text)
text_strings.extend(["(plaintext contains[cd] %@)"] * len(text))
format_strings.append(text_strings)
if password_protected is not None and notes:
password_string = (
["(passwordProtected == TRUE)"]
if password_protected
else ["(passwordProtected == FALSE)"]
)
format_strings.append(password_string)
if id and notes:
id_string = ["(id == %@)"] * len(id)
format_strings.append(id_string)
if format_strings:
# have one or more search predicates; filter notes
args = name or []
args += body or []
if text:
args += text * 2
args += id or []
or_strings = [" OR ".join(strings) for strings in format_strings]
format_str = "(" + ") AND (".join(or_strings) + ")"
predicate = AppKit.NSPredicate.predicateWithFormat_(format_str, *args)
notes = notes.filteredArrayUsingPredicate_(predicate)
return [Note(note) for note in notes.get()]
```
--------------------------------
### Get NotesList with Filtering - Python
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a NotesList object, optionally filtering notes by name, body, text, password protection status, or ID. This is a convenience wrapper around the `_noteslist` method.
```python
def noteslist(
self,
name: list[str] | None = None,
body: list[str] | None = None,
text: list[str] | None = None,
password_protected: bool | None = None,
id: list[str] | None = None,
) -> "NotesList":
"""Return NoteList object for all notes contained in account or notes filtered by property.
Args:
name: list of note names to filter by
body: list of note bodies to filter by
text: list of note text to filter by
password_protected: filter by password protected notes
id: list of note ids to filter by
Returns:
NotesList object"""
notes = self._noteslist(name, body, text, password_protected, id)
return NotesList(notes)
```
--------------------------------
### Get NoteList by Filter - Python
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a NotesList object, which is a collection of notes filtered by name, body, text, password protection status, ID, or account. Use this for batch operations on notes.
```python
def noteslist(
self,
name: list[str] | None = None,
body: list[str] | None = None,
text: list[str] | None = None,
password_protected: bool | None = None,
id: list[str] | None = None,
accounts: list[str] | None = None,
) -> "NotesList":
"""Return NoteList object for all notes contained in account or notes filtered by property.
Args:
name: list of note names to filter by
body: list of note bodies to filter by
text: list of note text to filter by
password_protected: filter by password protected notes
id: list of note ids to filter by
accounts: list of account names to filter by
Returns:
NotesList object
"""
account_list = self.app.accounts()
if accounts:
format_str = "name == %@" + " OR name == %@ " * (len(accounts) - 1)
predicate = AppKit.NSPredicate.predicateWithFormat_(format_str, accounts)
account_list = account_list.filteredArrayUsingPredicate_(predicate)
noteslists = [
Account(account)._noteslist(
name=name,
body=body,
text=text,
password_protected=password_protected,
id=id,
)
for account in account_list
]
return NotesList(*noteslists)
```
--------------------------------
### Get Notes List Object
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a NotesList object containing notes filtered by specified properties. This is useful for batch operations or when you need a collection of notes rather than individual Note objects.
```python
notes_list = notes_app.noteslist(accounts=['iCloud'])
```
--------------------------------
### Get NotesList Object
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a NotesList object containing notes filtered by specified properties such as name, body, text, password protection, or ID. This method is similar to `notes` but returns a NotesList object.
```python
def noteslist(
self,
name: list[str] | None = None,
body: list[str] | None = None,
text: list[str] | None = None,
password_protected: bool | None = None,
id: list[str] | None = None,
) -> "NotesList":
"""Return NoteList object for all notes contained in account or notes filtered by property.
Args:
name: list of note names to filter by
body: list of note bodies to filter by
text: list of note text to filter by
```
--------------------------------
### Show notes version and help
Source: https://rhettbull.github.io/macnotesapp/cli
Use the -v or --version flag to display the version of the notes CLI. Use --help to show the main help message and exit.
```bash
notes [OPTIONS] COMMAND [ARGS]...
```
```bash
-v, --version Show the version and exit.
```
```bash
--help Show this message and exit.
```
--------------------------------
### __init__()
Source: https://rhettbull.github.io/macnotesapp/reference
Initializes a new NotesApp object, establishing a connection to the Notes.app.
```APIDOC
## __init__()
### Description
create new NotesApp object
```
--------------------------------
### Get Folder ID
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves the unique identifier for the folder. It attempts to get the ID directly from the folder object, falling back to parsing it if necessary.
```python
@cached_property
def id(self) -> str:
"""ID of folder"""
return (
str(folder_id)
if (folder_id := self._folder.id())
else str(parse_id_from_object(self._folder.get()))
)
```
--------------------------------
### Initialize NotesApp
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new NotesApp object to interact with the Notes.app instance. This is the entry point for all Notes.app operations.
```python
notes_app = NotesApp()
```
--------------------------------
### Get Default Folder Name
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves the name of the default folder for the Notes.app account. It attempts to get the default folder object and its name, with a script fallback.
```python
@property
def default_folder(self) -> str:
"""Return name of default folder for account"""
if default_folder := self._account.defaultFolder():
return str(default_folder.name())
return str(self._run_script("accountGetDefaultFolder"))
```
--------------------------------
### show()
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the account interface within the Notes.app.
```APIDOC
## show()
### Description
Show account in Notes.app UI
### Parameters
None
### Request Example
```json
{}
```
### Response
#### Success Response (200)
This method does not return a value, but triggers the UI display.
#### Response Example
None
```
--------------------------------
### activate()
Source: https://rhettbull.github.io/macnotesapp/reference
Brings the Notes.app to the foreground, making it the active application.
```APIDOC
## activate()
### Description
Activate Notes.app
```
--------------------------------
### Create a New Note with Attachments
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note within the default account and adds specified attachments. Ensure the 'Account' and 'Note' classes are properly initialized and the 'add_attachment' method is available.
```python
account = Account(self.app.defaultAccount())
note = account.make_note(name, body)
if attachments:
for attachment in attachments:
note.add_attachment(attachment)
return note
```
--------------------------------
### Initialize NotesApp Object
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new NotesApp object, which serves as the entry point for interacting with the Notes application via ScriptingBridge.
```python
def __init__(self):
"""create new NotesApp object"""
self._app = ScriptingBridge.SBApplication.applicationWithBundleIdentifier_(
"com.apple.Notes"
)
```
--------------------------------
### Get Note as Dictionary
Source: https://rhettbull.github.io/macnotesapp/reference
Converts a note object into a dictionary representation. Useful for serialization or inspection.
```python
def asdict(self) -> dict[str, Any]:
"""Return dict representation of note"""
return {
"account": self.account,
"id": self.id,
"name": self.name,
"body": self.body,
"plaintext": self.plaintext,
"creation_date": self.creation_date,
"modification_date": self.modification_date,
"password_protected": self.password_protected,
"folder": self.folder,
}
```
--------------------------------
### Initialize Account Object
Source: https://rhettbull.github.io/macnotesapp/reference
Initializes the Account object with a ScriptingBridge SBObject.
```python
def __init__(self, account: ScriptingBridge.SBObject):
"""Initialize Account object"""
self._account = account
```
--------------------------------
### Initialize Folder Object
Source: https://rhettbull.github.io/macnotesapp/reference
Initializes a Folder object using a ScriptingBridge SBObject. This is the primary way to create a Folder instance.
```python
class Folder:
"""Folder object"""
def __init__(self, folder: ScriptingBridge.SBObject):
self._folder = folder
```
--------------------------------
### Create New Note with Attachments
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note in the default folder of the default account. It supports adding a name, HTML body, and an optional list of file attachments.
```python
def make_note(
self, name: str, body: str, attachments: list[str] | None = None
) -> "Note":
"""Create new note in default folder of default account.
Args:
name: name of notes
body: body of note as HTML text
attachments: optional list of paths to attachments to add to note
Returns:
newly created Note object
"""
# reference: https://developer.apple.com/documentation/scriptingbridge/sbobject/1423973-initwithproperties
account = Account(self.app.defaultAccount())
note = account.make_note(name, body)
if attachments:
for attachment in attachments:
note.add_attachment(attachment)
return note
```
--------------------------------
### notes help
Source: https://rhettbull.github.io/macnotesapp/cli
Prints help information for the 'notes' command or specific topics/subtopics.
```APIDOC
## help
Print help; for help on commands: help .
### Usage:
```
notes help [OPTIONS] [TOPIC] [SUBTOPIC]
```
### Options:
```
--help Show this message and exit.
```
```
--------------------------------
### Get Note Count
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total number of notes within the NotesList object. This is a standard Python len() operation.
```python
def __len__(self) -> int:
"""Return count of notes in list"""
return len(self.id)
```
--------------------------------
### make_note(name, body, attachments=None)
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note within the default folder of the default account. Optionally includes specified attachments.
```APIDOC
## make_note(name, body, attachments=None)
### Description
Create new note in default folder of default account.
### Parameters
#### Path Parameters
- **name** (str) - Required - name of notes
- **body** (str) - Required - body of note as HTML text
- **attachments** (list[str] | None) - Optional - optional list of paths to attachments to add to note
### Returns
- **'Note'** - newly created Note object
```
--------------------------------
### Create New Note
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note with a specified name and body content in the default folder of the default account. Optionally, attachments can be added by providing a list of file paths.
```python
new_note = notes_app.make_note(name='My New Note', body='Hello
This is the content.
', attachments=['/path/to/image.png'])
```
--------------------------------
### List notes with filtering
Source: https://rhettbull.github.io/macnotesapp/cli
List notes, with options to filter by account. Multiple accounts can be specified to include notes from several accounts.
```bash
notes list [OPTIONS] TEXT
```
```bash
-a, --account ACCOUNT Limit results to account ACCOUNT; may be repeated to
```
```bash
include multiple accounts.
```
```bash
--help Show this message and exit.
```
--------------------------------
### Get Folder Object by Name
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a ScriptingBridge folder object based on its name. Raises a ValueError if the specified folder cannot be found.
```python
def _folder_for_name(self, folder: str) -> ScriptingBridge.SBObject:
"""Return ScriptingBridge folder object for folder"""
if folder_objs := self._account.folders().filteredArrayUsingPredicate_(
AppKit.NSPredicate.predicateWithFormat_("name == %@", folder)
):
return folder_objs[0]
else:
raise ValueError(f"Could not find folder {folder}")
```
--------------------------------
### Initialize Account Object
Source: https://rhettbull.github.io/macnotesapp/reference
Initializes an Account object with a ScriptingBridge SBObject representing a Notes.app account. This is the primary way to interact with an account's data.
```python
class Account:
"""Notes.app Account object"""
def __init__(self, account: ScriptingBridge.SBObject):
"""Initialize Account object"""
self._account = account
```
--------------------------------
### Get Account ID
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves the unique identifier for the Notes.app account. This property uses a cached property to ensure the ID is fetched only once.
```python
@cached_property
def id(self) -> str:
"""Return ID of account"""
if id_ := self._account.id():
return str(id_)
return str(self._run_script("accountID"))
```
--------------------------------
### Configure default settings
Source: https://rhettbull.github.io/macnotesapp/cli
Use the 'notes config' command to configure default settings for the notes CLI, such as the default account or editor.
```bash
notes config [OPTIONS]
```
```bash
--help Show this message and exit.
```
--------------------------------
### version: str
Source: https://rhettbull.github.io/macnotesapp/reference
Fetches the version string of the Notes.app.
```APIDOC
## version: str
### Description
Return version of Notes.app
```
--------------------------------
### show
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the account interface within the Notes.app UI.
```APIDOC
## show
### Description
Show account in Notes.app UI
### Signature
```python
show(self)
```
```
--------------------------------
### show()
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the current note in the Notes.app user interface.
```APIDOC
## show()
### Description
Show note in Notes.app UI.
```
--------------------------------
### NotesApp Methods
Source: https://rhettbull.github.io/macnotesapp/reference
Methods for retrieving and creating notes.
```APIDOC
## NotesApp Methods
### `notes`
- **Description**: Retrieves a list of `Note` objects, optionally filtered by various properties.
- **Parameters**:
- `name` (list[str], optional): Filter notes by their names.
- `body` (list[str], optional): Filter notes by their body content.
- `text` (list[str], optional): Filter notes by their text content.
- `password_protected` (bool, optional): Filter notes based on whether they are password protected.
- `id` (list[str], optional): Filter notes by their unique IDs.
- `accounts` (list[str], optional): Filter notes by the account they belong to.
- **Returns**: `list[Note]` - A list of matching `Note` objects.
### `noteslist`
- **Description**: Retrieves a `NotesList` object containing notes, optionally filtered by various properties. This method aggregates notes from specified accounts.
- **Parameters**:
- `name` (list[str], optional): Filter notes by their names.
- `body` (list[str], optional): Filter notes by their body content.
- `text` (list[str], optional): Filter notes by their text content.
- `password_protected` (bool, optional): Filter notes based on whether they are password protected.
- `id` (list[str], optional): Filter notes by their unique IDs.
- `accounts` (list[str], optional): Filter notes by the account names they belong to.
- **Returns**: `NotesList` - A `NotesList` object containing the filtered notes.
### `make_note`
- **Description**: Creates a new note in the default folder of the default account.
- **Parameters**:
- `name` (str): The name (title) of the new note.
- `body` (str): The content of the note, provided as HTML text.
- `attachments` (list[str], optional): A list of file paths to be attached to the new note.
- **Returns**: `Note` - The newly created `Note` object.
```
--------------------------------
### Get Selected Notes
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a list of Note objects corresponding to the notes currently selected in the Notes.app interface. This is useful for acting on user-selected items.
```python
selected_notes = notes_app.selection
```
--------------------------------
### show
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the note in the Apple Notes application UI.
```APIDOC
## show
### Description
Shows the note in the Notes.app UI.
### Method
- **show()**
```
--------------------------------
### asdict()
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a list of dictionaries, where each dictionary represents a note with its attributes.
```APIDOC
## asdict()
### Description
Return list of dict representations of note
### Returns
- list[dict[str, str]]: A list of dictionaries, each containing note details like id, name, body, creation_date, modification_date, password_protected, and folder.
```
--------------------------------
### notes config
Source: https://rhettbull.github.io/macnotesapp/cli
Configures default settings for the 'notes' CLI, such as account and editor.
```APIDOC
## config
Configure default settings for account, editor, etc.
### Usage:
```
notes config [OPTIONS]
```
### Options:
```
--help Show this message and exit.
```
```
--------------------------------
### Account Methods
Source: https://rhettbull.github.io/macnotesapp/reference
Methods for interacting with the Account object, including iteration, folder access, and note creation.
```APIDOC
## __init__(account)
Initialize Account object
## __iter__()
Generator to yield all notes contained in Notes.app
## __len__()
Return count of notes
## folder(folder)
Return Folder object for folder with name folder.
## make_note(name, body, folder=None, attachments=None)
Create new note in account
Parameters:
Name | Type | Description | Default
---|---|---|---
`name` | `str` | name of note | _required_
`body` | `str` | body of note | _required_
`folder` | `str | None` | optional folder to create note in; if None, uses default folder | `None`
`attachments` | `list[str] | None` | optional list of file paths to attach to note | `None`
Returns:
Type | Description
---|---
`'Note'` | Note object for new note
Raises:
Type | Description
---|---
`ScriptingBridgeError` | if note could not be created
`FileNotFoundError` | if attachment file could not be found
```
--------------------------------
### make_note
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note within the Notes application. Supports setting a name, body, folder, and attachments.
```APIDOC
## make_note
### Description
Create new note in account.
### Signature
```python
make_note(self, name: str, body: str, folder: str | None = None, attachments: list[str] | None = None) -> "Note"
```
### Parameters
#### name
(str) - name of note
#### body
(str) - body of note
#### folder
(str | None) - optional folder to create note in; if None, uses default folder
#### attachments
(list[str] | None) - optional list of file paths to attach to note
### Returns
Note object for new note
### Raises
- ScriptingBridgeError: if note could not be created
- FileNotFoundError: if attachment file could not be found
```
--------------------------------
### Create a New Note in Notes.app
Source: https://rhettbull.github.io/macnotesapp/reference
Use this function to create a new note with a specified name, body, and optional folder and attachments. It handles file existence checks for attachments and raises errors if the note creation fails.
```python
def make_note(
self,
name: str,
body: str,
folder: str | None = None,
attachments: list[str] | None = None,
) -> "Note":
"""Create new note in account
Args:
name: name of note
body: body of note
folder: optional folder to create note in; if None, uses default folder
attachments: optional list of file paths to attach to note
Returns:
Note object for new note
Raises:
ScriptingBridgeError: if note could not be created
FileNotFoundError: if attachment file could not be found
"""
# reference: https://developer.apple.com/documentation/scriptingbridge/sbobject/1423973-initwithproperties
notes_app = NotesApp()
folder_obj = (
self._folder_for_name(folder) if folder else self._account.defaultFolder()
)
properties = {
"body": f"{name}
\n{body}",
}
note = (
notes_app.app.classForScriptingClass_("note")
.alloc()
.initWithProperties_(properties)
)
notes = folder_obj.notes()
len_before = len(notes)
notes.addObject_(note)
len_after = len(notes)
if len_after <= len_before:
raise ScriptingBridgeError(
f"Could not create note '{name}' with body '{body}'"
)
new_note = Note(note)
if attachments:
for attachment in attachments:
if not os.path.exists(attachment):
raise FileNotFoundError(f"File {attachment} does not exist")
new_note.add_attachment(attachment)
return new_note
```
--------------------------------
### Create New Note
Source: https://rhettbull.github.io/macnotesapp/reference
Creates a new note in the account, optionally within a specific folder and with attachments. Raises FileNotFoundError if an attachment file does not exist.
```python
def make_note(
self,
name: str,
body: str,
folder: str | None = None,
attachments: list[str] | None = None,
) -> "Note":
"""Create new note in account
Args:
name: name of note
body: body of note
folder: optional folder to create note in; if None, uses default folder
attachments: optional list of file paths to attach to note
Returns:
Note object for new note
Raises:
ScriptingBridgeError: if note could not be created
FileNotFoundError: if attachment file could not be found
"""
# reference: https://developer.apple.com/documentation/scriptingbridge/sbobject/1423973-initwithproperties
notes_app = NotesApp()
folder_obj = (
self._folder_for_name(folder) if folder else self._account.defaultFolder()
)
properties = {
"body": f"{name}
\n{body}",
}
note = (
notes_app.app.classForScriptingClass_("note")
.alloc()
.initWithProperties_(properties)
)
notes = folder_obj.notes()
len_before = len(notes)
notes.addObject_(note)
len_after = len(notes)
if len_after <= len_before:
raise ScriptingBridgeError(
f"Could not create note '{name}' with body '{body}'"
)
new_note = Note(note)
if attachments:
for attachment in attachments:
if not os.path.exists(attachment):
raise FileNotFoundError(f"File {attachment} does not exist")
new_note.add_attachment(attachment)
return new_note
```
--------------------------------
### asdict()
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a dictionary representation of the note, including its account, ID, name, body, creation date, modification date, password protection status, and folder.
```APIDOC
## asdict()
### Description
Return dict representation of note.
### Returns
- **dict[str, Any]** - A dictionary containing the note's properties.
```
--------------------------------
### Print information about Notes accounts
Source: https://rhettbull.github.io/macnotesapp/cli
The 'notes accounts' command lists information about your Notes accounts. Use the -j or --json flag to print output in JSON format.
```bash
notes accounts [OPTIONS]
```
```bash
-j, --json Print output in JSON format.
```
```bash
--help Show this message and exit.
```
--------------------------------
### Activate Notes.app
Source: https://rhettbull.github.io/macnotesapp/reference
Brings the Notes application to the foreground, making it the active application. This is a utility function for user interaction.
```python
def activate(self) -> None:
"""Activate Notes.app"""
run_script("notesActivate")
```
--------------------------------
### __iter__
Source: https://rhettbull.github.io/macnotesapp/reference
Allows iteration over all notes within the account.
```APIDOC
## __iter__
### Description
Iterate over all notes in the account.
### Signature
```python
__iter__(self) -> Generator[Note, None, None]
```
### Returns
A generator yielding Note objects
```
--------------------------------
### Iterate Through Notes
Source: https://rhettbull.github.io/macnotesapp/reference
Generates all notes contained within the Notes.app for the current account.
```python
def __iter__(self) -> Generator[Note, None, None]:
"""Generator to yield all notes contained in Notes.app"""
for note in self._account.notes():
yield Note(note)
```
--------------------------------
### NotesList Methods
Source: https://rhettbull.github.io/macnotesapp/reference
Methods available for the NotesList object.
```APIDOC
## NotesList Methods
This section details the methods available for the `NotesList` object.
### `__len__()`
Return count of notes in list.
### `asdict() -> list[dict[str, str]]`
Return list of dict representations of note. Each dictionary contains the following keys: `id`, `name`, `body`, `plaintext`, `creation_date`, `modification_date`, `password_protected`, and `folder`.
```
--------------------------------
### List All Accounts
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a list of all available account names configured in Notes.app. This is useful for understanding where notes are stored.
```python
accounts = notes_app.accounts
```
--------------------------------
### Run AppleScript
Source: https://rhettbull.github.io/macnotesapp/reference
Internal helper method to execute an AppleScript command with provided arguments. It handles passing the account and note ID to the script.
```python
def _run_script(self, script: str, *args):
"""Run AppleScript script"""
return run_script(script, self.account, self.id, *args)
```
--------------------------------
### Activate Notes.app
Source: https://rhettbull.github.io/macnotesapp/reference
Brings the Notes application to the foreground. This function relies on an external script named 'notesActivate'.
```python
run_script("notesActivate")
```
--------------------------------
### app
Source: https://rhettbull.github.io/macnotesapp/reference
Provides access to the ScriptingBridge SBApplication object for Notes.app.
```APIDOC
## app
### Description
Return Notes.app SBApplication object
```
--------------------------------
### Account.noteslist()
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieve a NoteList object for notes within the account, with optional filtering.
```APIDOC
## Account.noteslist()
### Description
Return NoteList object for all notes contained in account or notes filtered by property.
### Parameters
#### Query Parameters
- **name** (list[str] | None): Filter notes by a list of note names.
- **body** (list[str] | None): Filter notes by a list of note bodies.
- **text** (list[str] | None): Filter notes by a list of note text content (name and body).
- **password_protected** (bool | None): Filter notes by their password protection status (True for protected, False for not protected).
- **id** (list[str] | None): Filter notes by a list of note IDs.
### Returns
- NotesList: A NotesList object containing notes matching the specified filters.
```
--------------------------------
### asdict
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a dictionary representation of the note, including its account, ID, name, body, dates, and protection status.
```APIDOC
## asdict
### Description
Returns a dictionary representation of the note.
### Returns
- **dict[str, Any]**: A dictionary containing the note's properties.
```
--------------------------------
### Show Note in UI
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the note in the native macOS Notes application UI. This method triggers the application's interface to bring the specified note to the foreground.
```python
def show(self):
"""Show note in Notes.app UI"""
self._run_script("noteShow")
```
--------------------------------
### accounts: list[str]
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a list of all available account names in Notes.app.
```APIDOC
## accounts: list[str]
### Description
Return list of accounts
```
--------------------------------
### Show Account in Notes.app UI
Source: https://rhettbull.github.io/macnotesapp/reference
Triggers the display of the current account within the Notes.app user interface.
```python
def show(self):
"""Show account in Notes.app UI"""
self._run_script("accountShow")
```
--------------------------------
### selection: list['Note']
Source: https://rhettbull.github.io/macnotesapp/reference
Returns a list of Note objects corresponding to the currently selected notes in the Notes.app interface.
```APIDOC
## selection: list['Note']
### Description
Return lit of Note objects for selected notes
```
--------------------------------
### Show Account in Notes.app - Python
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the current account within the Notes.app user interface. This function triggers the UI action.
```python
def show(self):
"""Show account in Notes.app UI"""
self._run_script("accountShow")
```
--------------------------------
### account(account=None)
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves an Account object for a specified account name, or the default account if none is provided.
```APIDOC
## account(account=None)
### Description
Return Account object for account or default account if account is None.
### Parameters
#### Path Parameters
- **account** (str) - Optional - name of account to return. If None, return default account.
### Returns
- **'Account'** - Account object
```
--------------------------------
### Yield All Notes from Account
Source: https://rhettbull.github.io/macnotesapp/reference
Use this generator to iterate through all notes within a Notes.app account. Requires an initialized account object.
```python
"""Generator to yield all notes contained in Notes.app"""
for note in self._account.notes():
yield Note(note)
```
--------------------------------
### Add a new note
Source: https://rhettbull.github.io/macnotesapp/cli
Add a new note to Apple Notes. Notes can be added from standard input, a string, by opening an editor, or by downloading a URL. Options allow specifying the account, folder, and format (plain text, HTML, Markdown).
```bash
notes add [OPTIONS] NOTE
```
```bash
notes add
```
```bash
cat file.txt | notes add
```
```bash
notes add < file.txt
```
```bash
notes add NOTE
```
```bash
notes add --edit
```
```bash
notes add -e
```
```bash
notes add --url URL
```
```bash
notes add -u URL
```
```bash
-s, --show Show note in Notes after adding.
```
```bash
-F, --file FILENAME
```
```bash
-u, --url URL
```
```bash
-h, --html Use HTML for body of note.
```
```bash
-m, --markdown Use Markdown for body of note.
```
```bash
-p, --plaintext Use plaintext for body of note (default unless
```
```bash
changed in `notes config`).
```
```bash
-e, --edit Edit note text before adding in default editor.
```
```bash
-a, --account ACCOUNT Add note to account ACCOUNT.
```
```bash
-f, --folder FOLDER Add note to folder FOLDER.
```
```bash
--help Show this message and exit.
```
--------------------------------
### Application Control
Source: https://rhettbull.github.io/macnotesapp/reference
Methods to control the Notes.app application, including activating and quitting.
```APIDOC
## activate
### Description
Activate Notes.app
### Method
None (function call)
### Returns
None
```
```APIDOC
## quit
### Description
Quit Notes.app
### Method
None (function call)
### Returns
None
```
--------------------------------
### Print note content
Source: https://rhettbull.github.io/macnotesapp/cli
Display the content of one or more notes to standard output. Supports outputting as plain text, Markdown, HTML, or JSON. The default JSON body format is HTML.
```bash
notes cat [OPTIONS] NOTE_NAME
```
```bash
-p, --plaintext Output note as plain text.
```
```bash
-m, --markdown Output note as Markdown.
```
```bash
-h, --html Output note as HTML.
```
```bash
-j, --json Output note as JSON. The default format for the note body
```
```bash
in JSON is HTML (this is how the note is stored in Notes).
```
```bash
If --plaintext or --markdown is also specified, the note
```
```bash
body in the resulting JSON will be in the specified format.
```
```bash
--help Show this message and exit.
```
--------------------------------
### Account.notes()
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieve a list of Note objects from the account, with optional filtering capabilities.
```APIDOC
## Account.notes()
### Description
Return Note object for all notes contained in account or notes filtered by property.
### Parameters
#### Query Parameters
- **name** (list[str] | None): Filter notes by a list of note names.
- **body** (list[str] | None): Filter notes by a list of note bodies.
- **text** (list[str] | None): Filter notes by a list of note text content (name and body).
- **password_protected** (bool | None): Filter notes by their password protection status (True for protected, False for not protected).
- **id** (list[str] | None): Filter notes by a list of note IDs.
### Returns
- list[Note]: A list of Note objects matching the specified filters.
```
--------------------------------
### Show Note in UI
Source: https://rhettbull.github.io/macnotesapp/reference
Displays the note in the macOS Notes application UI. This function directly calls an AppleScript command.
```python
def show(self):
"""Show note in Notes.app UI"""
self._run_script("noteShow")
```
--------------------------------
### NotesApp Properties
Source: https://rhettbull.github.io/macnotesapp/reference
Access properties of the Notes.app instance.
```APIDOC
## NotesApp Properties
### `accounts`
- **Description**: Returns a list of all available account names in Notes.app.
- **Type**: `list[str]`
### `default_account`
- **Description**: Returns the name of the default account configured in Notes.app.
- **Type**: `str`
### `selection`
- **Description**: Returns a list of `Note` objects representing the currently selected notes in the Notes.app interface.
- **Type**: `list[Note]`
### `version`
- **Description**: Returns the version string of the Notes.app.
- **Type**: `str`
```
--------------------------------
### notes list
Source: https://rhettbull.github.io/macnotesapp/cli
Lists notes, with options to filter by account or text content.
```APIDOC
## list
List notes, optionally filtering by account or text.
### Usage:
```
notes list [OPTIONS] TEXT
```
### Options:
```
-a, --account ACCOUNT Limit results to account ACCOUNT; may be repeated to
include multiple accounts.
--help Show this message and exit.
```
```
--------------------------------
### Add Attachment to Note
Source: https://rhettbull.github.io/macnotesapp/reference
Use this method to attach a file to a note. Ensure the file path is correctly resolved. This operation uses AppleScript and may take a few hundred milliseconds.
```python
def add_attachment(self, path: str) -> "Attachment":
"""Add attachment to note
Args:
path: path to file to attach
Returns:
Attachment object for attached file
Raises:
FileNotFoundError: if file not found
"""
# Implementation note:
# this is currently done with AppleScript which takes ~300ms on M1 Mac
# it's faster with ScriptingBridge (~80ms) but when adding via ScriptingBridge
# the attachment sometimes is added twice
# See #15 for more details
# must pass fully resolved path to AppleScript
path = pathlib.Path(path).expanduser().resolve()
if not path.exists():
raise FileNotFoundError(f"File not found: {path}")
attachment_id = self._run_script("noteAddAttachment", str(path))
return Attachment(self._note.attachments().objectWithID_(attachment_id))
```
--------------------------------
### folder
Source: https://rhettbull.github.io/macnotesapp/reference
Retrieves a Folder object based on its name.
```APIDOC
## folder
### Description
Return Folder object for folder with name folder.
### Signature
```python
folder(self, folder: str) -> "Folder"
```
### Parameters
#### folder
(str) - name of the folder
### Returns
Folder object for the specified folder
```
--------------------------------
### __len__
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total count of notes within the account.
```APIDOC
## __len__
### Description
Return count of notes
### Signature
```python
__len__(self) -> int
```
### Returns
(int) - The number of notes in the account
```
--------------------------------
### __len__()
Source: https://rhettbull.github.io/macnotesapp/reference
Returns the total count of notes across all accounts in Notes.app.
```APIDOC
## __len__()
### Description
Return count of notes in Notes.app
```
--------------------------------
### Iterate Through All Notes
Source: https://rhettbull.github.io/macnotesapp/reference
Provides a generator that yields a Note object for every note contained within the Notes application. It iterates through all accounts and then through all notes within each account.
```python
for account in self.app.accounts():
notes = account.notes()
for note in notes:
yield Note(note)
```
--------------------------------
### __iter__()
Source: https://rhettbull.github.io/macnotesapp/reference
Provides a generator that yields Note objects for every note contained within Notes.app.
```APIDOC
## __iter__()
### Description
Generator to yield Note object for all notes contained in Notes.app
```
--------------------------------
### Note Equality Check
Source: https://rhettbull.github.io/macnotesapp/reference
Defines equality between two Note objects based on their ID and account. This allows for direct comparison of Note instances.
```python
def __eq__(self, other: "Note"):
return (self.id, self.account) == (other.id, other.account)
```