notesctl

AI-native CLI for Apple Notes on macOS.

Built for humans and machines alike — notesctl gives structured, scriptable access to Apple Notes via the terminal. Designed as a first-class tool for AI agents like OpenClaw, enabling autonomous note management through natural language.

Why AI-native?

• JSON output (--json) — machine-readable by default, ready for LLM tool-use and agent pipelines
• Quiet mode (--quiet) — zero noise for scripting and automation
• Short ID resolution — agents can reference notes by compact IDs instead of fragile indices
• Stdin piping — compose with other CLI tools and agent workflows seamlessly
• Exit codes & structured errors — agents can handle failures programmatically

OpenClaw Integration

notesctl works as an AgentSkill for OpenClaw, letting AI agents manage your Apple Notes autonomously:

"Search my notes for meeting action items" → notesctl search "action items" --json
"Create a note from this summary"          → notesctl add --title "Summary" --body "..."
"Append today's log to my journal"         → notesctl edit p123 --append "..."

Install

Homebrew

brew install biao29/tap/notesctl

From source

make build
# binary at ./bin/notesctl

Usage

notesctl                           # list notes (default)
notesctl list                      # list notes
notesctl list --folder Work        # filter by folder
notesctl list --all                # show all (no limit)

notesctl show 1                    # show note by index
notesctl show p123                 # show note by short ID
notesctl show p123 --raw           # output raw HTML

notesctl search "meeting notes"    # search by title and content

notesctl add "Quick thought"
notesctl add --title "Ideas" --body "List of ideas..." --folder Work
echo "Piped content" | notesctl add -q

notesctl edit p123 --title "New title"
notesctl edit 1 --append "Additional notes"
echo "more" | notesctl edit p123 --append -

notesctl move 1 --to Archive
notesctl delete p123 --force

notesctl folders                   # list folders
notesctl folders "Work" --create
notesctl folders "Old" --delete

notesctl status                    # check automation permission

Output formats

• --json / -j emits JSON objects (ideal for AI agents and scripting).
• --plain emits tab-separated lines.
• --quiet / -q suppresses output (useful for fire-and-forget commands).

Aliases

Alias	Command
ls	list
cat	show
find	search
new	add
append	edit --append
mv	move
rm	delete

Development

make help                          # show all targets
make notesctl ARGS="list"          # clean build + run with args
make test                          # run tests with coverage
make check                         # lint + test + coverage gate
make format                        # auto-format sources
make clean                         # swift package clean

Requirements

• macOS 14+ (Sonoma or later)
• Swift 6+

Project structure

Sources/
  NoteCore/        # Core Notes API (AppleScript IPC, models)
  notesctl/        # CLI (commands, formatting, routing)
Tests/
  NoteCoreTests/   # Unit tests for NoteCore
  notesctlTests/   # Unit tests for CLI

Permissions

notesctl uses AppleScript to communicate with Notes.app. On first run, macOS will prompt you to allow Automation access. If denied, enable Terminal (or notesctl) in System Settings > Privacy & Security > Automation.

Run notesctl status to check authorization.