Skip to content

SKILL.md

Latest commit

 

History

History
106 lines (79 loc) · 4.42 KB

SKILL.md

File metadata and controls

106 lines (79 loc) · 4.42 KB
Raw
name apple-notes
description Manage Apple Notes via the notesctl CLI on macOS (list, search, create, edit, move, delete). Supports folders, JSON output, and stdin piping.
homepage https://github.com/biao29/notesctl
license MIT
metadata
author version openclaw
biao29
1.0.0
emoji requires
📝
bins
notesctl

Apple Notes

CLI tool for managing Apple Notes on macOS. Always respond in the user's language.

Prerequisites

  • macOS 14+ (Sonoma or later)
  • notesctl binary installed
brew install biao29/tap/notesctl
# or download from GitHub Releases:
# curl -L https://github.com/biao29/notesctl/releases/latest/download/notesctl-macos.zip -o /tmp/notesctl.zip && unzip /tmp/notesctl.zip -d /usr/local/bin

Verify: notesctl status

On first run, macOS prompts for Automation permission. If denied, the user must enable it in System Settings > Privacy & Security > Automation.

Quick Reference

# List & Search
notesctl list --json                         # list notes (default command)
notesctl list --folder Work --json           # filter by folder
notesctl list --all --json                   # show all (no limit)
notesctl search "query" --json               # search by title and content

# Show
notesctl show <id> --json                    # show note content
notesctl show <id> --raw                     # output raw HTML

# Create
notesctl add --title "..." --body "..."      # create note
notesctl add --title "..." --folder Work     # create in specific folder
notesctl add "Quick thought"                 # positional title
echo "content" | notesctl add -q             # create from stdin, quiet

# Edit
notesctl edit <id> --title "New title"       # update title
notesctl edit <id> --body "New body"         # replace body
notesctl edit <id> --append "Extra text"     # append to note
echo "more" | notesctl edit <id> --append -  # append from stdin

# Organize
notesctl move <id> --to Archive              # move note to folder
notesctl delete <id> --force                 # delete note (--force required in non-TTY)

# Folders
notesctl folders --json                      # list folders
notesctl folders "Work" --create             # create folder
notesctl folders "Old" --delete              # delete folder

Aliases: ls=list, cat/get=show, find=search, new/create=add, append=edit --append, mv=move, rm=delete

Output Formats

Flag Output Use case
--json / -j JSON objects AI agent workflows (preferred)
--plain Tab-separated Shell scripting and piping
--quiet / -q Minimal / none Fire-and-forget operations
(default) Human-readable Interactive terminal use

Always use --json when processing output programmatically. The stderr spinner is automatically suppressed in --json, --quiet, and non-TTY environments.

ID System

Notes can be referenced three ways:

  1. Index (1-based) — positional, changes when notes are added/removed
  2. Short ID (p123) — stable, derived from CoreData URI, persists across sessions
  3. Full CoreData URL — internal identifier, rarely needed

Use short IDs for stable references. Prefix matching works (minimum 2 characters); if ambiguous, notesctl reports all matches.

Error Handling

Error Exit code Action
automationDenied 1 Guide user to enable permission: System Settings > Privacy & Security > Automation
noteNotFound 2 Note ID/index is invalid — ask user to verify
folderNotFound 2 Folder name is wrong — list folders first with notesctl folders --json
ambiguousIdentifier 1 Multiple notes match — show the matches, ask user to pick
invalidIdentifier 1 ID format is wrong — use index, short ID (p123), or full URL
passwordProtected 1 Cannot modify locked notes — inform user, suggest manual action in Notes.app

Exit codes: 0 = success, 1 = general error, 2 = not found.

Tips

  • Always use --json to get machine-readable output for programmatic processing
  • Use short IDs (p123) instead of indices for stable cross-session references
  • After creating a note, use --quiet to capture just the short ID
  • Combine with other CLI tools via stdin piping: pbpaste | notesctl add -q
  • delete requires --force in non-TTY (scripting/agent) contexts
  • Password-protected notes are read-only — cannot edit, move, or delete