better bear
A CLI and MCP server for Bear notes via CloudKit. Use it from the terminal or let Claude read, search, and edit your notes.
curl -sL https://raw.githubusercontent.com/mreider/better-bear-cli/main/install.sh | bash
CLI
Create, search, edit, tag, and attach files from the terminal.
MCP Server
22 tools for Claude Desktop to manage your notes.
CloudKit
Same API as Bear Web. Syncs to all devices.
Open Source
MIT licensed. Universal macOS binary.
Install & Upgrade
Quick install
curl -sL https://raw.githubusercontent.com/mreider/better-bear-cli/main/install.sh | bash
bcli authUpgrade
bcli upgrade # download latest
bcli upgrade --check # check onlyRun hash -r after upgrading. Restart Claude Desktop if using MCP.
Build from source
git clone https://github.com/mreider/better-bear-cli.git
cd better-bear-cli && swift build -c release
cp .build/release/bcli ~/.local/bin/bcliNotes & Search
| bcli ls | List notes |
| bcli ls --tag work --json | Filter by tag, JSON output |
| bcli ls --untagged | Notes with no tags |
| bcli ls --archived | Archived notes |
| bcli ls --trashed | Trashed notes |
| bcli get <id> | View note with metadata |
| bcli get <id> --raw | Just the markdown |
| bcli get <id> --json | JSON output (includes parsed front matter) |
| bcli search "query" | Full-text search (title, tags, body) |
| bcli search "q" --since yesterday | Modified after date |
| bcli search "q" --before 2026-06-01 | Modified before date |
Date filters: today yesterday last-week last-month last-year or YYYY-MM-DD
Create & Edit
| bcli create "Title" -b "Body" | Create a note |
| bcli create "T" -t "t1,t2" | With tags |
| bcli create "T" --stdin | Body from stdin |
| bcli create "T" --fm "status=draft" | With YAML front matter |
| bcli edit <id> --append "text" | Append to end |
| bcli edit <id> --append "x" --after "Heading" | Insert after a heading |
| bcli edit <id> --replace-section "H" --section-content "new" | Replace section content |
| bcli edit <id> --editor | Open in $EDITOR |
| bcli edit <id> --stdin | Replace from stdin |
Attachments
Uploads to iCloud. Images (jpg, png, gif, webp, heic, svg) render inline. Other files embed.
| bcli attach <id> photo.jpg | Append image to note |
| bcli attach <id> img.png --after "Profile" | After a heading |
| bcli attach <id> img.png --before "Footer" | Before text |
| bcli attach <id> img.png --prepend | After title |
| bcli attach name.png --base64 <data> | From base64 (programmatic) |
Archive, Trash & TODOs
| bcli archive <id> | Archive a note |
| bcli archive <id> --undo | Unarchive |
| bcli trash <id> | Move to trash |
| bcli todo | Notes with open TODOs |
| bcli todo <id> | View/toggle interactively |
| bcli todo <id> --toggle 3 | Toggle item 3 |
YAML Front Matter
Bear collapses --- blocks. Use for status, projects, dates, or any metadata.
| bcli create "T" --fm "status=draft" "project=alpha" | Create with front matter |
| bcli get <id> --json | Includes parsed frontmatter object |
| bcli edit <id> --set-fm "status=done" | Set/update a field |
| bcli edit <id> --remove-fm "draft" | Remove a field |
Library Tools
| bcli stats | Notes, words, tags, dates, top tags |
| bcli duplicates | Find notes with duplicate titles |
| bcli health | Health report: duplicates, empties, orphans, conflicts |
| bcli sync | Sync to local cache |
| bcli sync --full | Force full re-sync |
| bcli export ./dir | Export as markdown |
| bcli export --frontmatter | With YAML metadata |
| bcli export --tag work | Filter by tag |
| bcli upgrade | Self-update to latest release |
| bcli mcp install | Install MCP server for Claude Desktop |
MCP Server
22 tools for Claude Desktop. Install: cd mcp-server && npm install && npm run build && cd .. && bcli mcp install
| bear_sync | Sync from iCloud |
| bear_list_notes | List with tag/archive/trash filters |
| bear_get_note | Full content + parsed front matter |
| bear_search | Full-text search with date filters |
| bear_get_tags | Tag hierarchy with counts |
| bear_create_note | Create with tags and front matter |
| bear_edit_note | Append, replace, section edit, front matter |
| bear_attach_file | Upload image/file to iCloud |
| bear_archive_note | Archive or unarchive |
| bear_trash_note | Move to trash |
| bear_add_tag | Add tag to note |
| bear_remove_tag | Remove tag from note |
| bear_rename_tag | Rename across all notes |
| bear_delete_tag | Delete from all notes |
| bear_find_untagged | List untagged notes |
| bear_list_todos | Notes with incomplete TODOs |
| bear_get_todos | TODO items from a note |
| bear_toggle_todo | Toggle TODO completion |
| bear_note_stats | Library statistics |
| bear_find_duplicates | Find duplicate titles |
| bear_health_check | Library health report |
Scripts
Shell scripts for common workflows in scripts/:
| daily-note.sh | Create a daily note from template (skips if exists) |
| meeting-note.sh | Meeting note with attendees and action items |
| backup.sh | Export all notes + git commit (cron-friendly) |
| cleanup-empty.sh | Find and optionally trash empty notes |
| bulk-tag.sh | Add a tag to notes matching a search |
| stale-notes.sh | Find notes not modified in N days |
| weekly-review.sh | Summary of this week's activity |
| import-markdown.sh | Import a folder of .md files as notes |
How It Works
Same CloudKit REST API as Bear Web. Notes live in your iCloud private database. Does not touch Bear's local SQLite — safe to use with Bear open on any device.
