better bear

Full Reference

Notes & 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

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

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)

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

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

bcli context init	One-time setup
bcli context sync	Pull qualifying notes, reconcile, regenerate index
bcli context sync --force	Full re-sync
bcli context index	Show the index (table of contents)
bcli context fetch <path>	Load a specific file
bcli context search "query"	Full-text search across all files
bcli context add <id>	Tag a note with #context, sync
bcli context add <id> --subtag research	Tag as #context/research
bcli context remove <id>	Untag and remove from library
bcli context status	Health check: counts, tokens, staleness, warnings
bcli context import <file>	Import an external file into the library
bcli context import --stdin --filename note.md	Import from stdin
bcli context ingest	List untriaged files in inbox
bcli context triage <file> keep	Move inbox file to external
bcli context triage <file> push_to_bear	Create Bear note from inbox file
bcli context triage <file> discard	Delete inbox file
bcli context push <file>	Push an external file to Bear
bcli context remove-external <file>	Delete an external file

34 tools available in Claude Desktop, Claude Code, and any MCP client. npm: better-bear

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

bear_context_setup	Initialize the context library
bear_context_sync	Sync qualifying Bear notes to the library
bear_context_index	Get the index + freshness metadata
bear_context_fetch	Load specific files by path
bear_context_search	Full-text search across all files
bear_context_add	Tag a note for inclusion
bear_context_remove	Untag and remove a note
bear_context_status	Health stats and warnings
bear_context_import	Import external content (text via stdin)
bear_context_ingest	List untriaged inbox files
bear_context_triage	Triage an inbox file: keep, push to Bear, or discard
bear_context_push_to_bear	Push an external file to Bear as a note
bear_context_remove_external	Delete an external file

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

git clone https://github.com/KuvopLLC/better-bear.git
cd better-bear && swift build -c release
cp .build/release/bcli ~/.local/bin/bcli