How Bear CLI and MCP Reshape Apple-Native Note Automation

Bear has long been celebrated for its refined macOS and iOS native experience, typographic polish, and seamless CloudKit synchronization. Yet for developers and power users, its walled-garden architecture and longstanding lack of a CLI presented a frustrating barrier: notes were locked deep inside Core Data and SQLite databases, leaving virtually no clean way to interact via the command line.

With Bear 2.8, Shiny Frog introduced bearcli—a native command-line utility bundled directly within the macOS app package—alongside an official MCP Server built on Anthropic’s Model Context Protocol. This release eliminates the need to rely on brittle URL schemes or risk reverse-engineering SQLite databases, giving the design-forward note-taking app the modern automation layer it was missing in the age of AI agents.

Legacy Hurdles: The Flaws of x-callback-url and the Cost of the SQLite Black Box

Historically, developers looking to script or automate Bear from the terminal were left with only two paths—both carrying significant architectural penalties.

Three Critical Flaws of x-callback-url

Before bearcli, the only official programmatic interface was the URL scheme (x-callback-url) native to Apple platforms, structured like this:

 bear://x-callback-url/create
   ?title=Log&text=Hello&tags=journal

While x-callback-url worked adequately for simple capture in iOS Shortcuts, it posed three intolerable pain points for desktop developer workflows:

1. Focus Stealing: By default, triggering a URL scheme forces macOS to bring Bear’s GUI window straight to the foreground (only some endpoints honor a show_window=no opt-out), snatching focus away from the active editor and shattering developer flow.
2. Asynchronous & Disjointed Responses: Capturing return data required registering callback URLs or running local port listeners. Shell scripts, Makefiles, and CI/CD pipelines had no synchronous way to capture a newly created note ID, blocking downstream pipeline chaining.
3. Completely Paralyzed in Headless Environments: URL schemes cannot be parsed or handled in remote SSH sessions, macOS launchd background daemons, or headless terminal setups.

Data Corruption Risks of Direct SQLite Access

Frustrated by URL scheme constraints, some power users bypassed the GUI to access Bear’s underlying database files directly:

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

Executing raw INSERT or UPDATE statements against this SQLite store, however, introduced severe system-level risks:

• Core Data Cache Inconsistency: Bear’s desktop app relies on Apple’s Core Data framework and its in-memory managed object graph. When an external process mutates SQLite behind its back, the running GUI has no way to detect the change, leading to stale cache overwrites and silent data loss.
• Corrupted CloudKit Sync: Cross-device syncing depends on Core Data and CloudKit tombstones and change tokens. Bypassing the framework breaks the sync sequence, spawning persistent duplicate notes or ghost records across devices.
• Brittle Schema Migrations: Major Bear updates frequently refactor internal database schemas and encryption structures. External tools relying on reverse-engineered SQL schemas reliably break on updates.

bearcli: The Official Safe Broker

Fundamentally, bearcli acts as an official safe broker and bridge created by Shiny Frog. By hooking directly into Bear’s native engine, it:

• Ensures every write operation fires the complete set of Core Data lifecycle events.
• Automatically maintains CloudKit sync metadata and change token integrity.
• Operates 100% silently in the terminal background—no popups, no focus stealing, with full support for synchronous calls and structured error returns.

Engineers gain high-speed terminal automation without putting years of accumulated knowledge at risk.

Engineering Design: A Modern Architecture Grounded in Unix Philosophy

bearcli’s architectural design is remarkably robust, reflecting careful consideration for command-line piping and scripted automation workflows.

Bundled Native Binary

Written in native Swift with no external runtime dependencies, bearcli ships directly inside the macOS app bundle:

/Applications/Bear.app/Contents/MacOS/bearcli

A simple symlink makes it globally accessible from any shell:

sudo ln -s /Applications/Bear.app/Contents/MacOS/bearcli /usr/local/bin/bearcli

Multi-Format Output and Extended Markdown Support

bearcli offers three distinct output formats tailored to different automation scenarios:

1. TSV (Tab-Separated Values, default): Emits headerless lines ideally suited for piping into standard Unix utilities like awk, cut, xargs, or ripgrep.
2. Structured JSON (--format json): Emits standard JSON objects; on failure, errors are written to stdout as {"error":{"code":"...","message":"..."}}, making error handling in scripts straightforward.
3. Standards-Compliant CSV (--format csv): Fully adheres to the RFC 4180 standard with a header row, ready for direct ingestion into data analysis tools.

On the content side, bearcli natively preserves Bear’s rich Markdown extensions, including nested tags (#tag, #nested/child), bidirectional wiki links ([[Title]], [[Title|alias]]), highlights (==highlight== and color variants), underlines (~underline~), GitHub-style callouts (> [!NOTE]), and standard LaTeX math blocks ($math$).

Section-Level Addressing and Optimistic Concurrency Control

While conventional note-taking CLIs typically offer only blunt all-or-nothing read/write operations, bearcli introduces sophisticated section-level addressing:

• Unique heading addressing: --section "## Setup"
• Nested heading addressing: --section "# Build\n## Install"
• Indexed duplicate heading targeting: --section "# Build\n## Install\n2" (targets the second matching section)
• Preamble targeting: --section "## Install\npreamble" (targets the intro text between a heading and its first child subheading)

Running bearcli outline <note-id> provides external programs with the exact byte ranges and structured addresses of every section in a note.

For write safety, bearcli implements Optimistic Concurrency Control (OCC).

Reading a note or section with bearcli cat returns a unique hash receipt. A subsequent bearcli overwrite call can pass this receipt via --base <hash>; if the note changed between the read and the write, the update is immediately rejected, preventing race conditions. (CLI callers may omit --base for an unconditional write; calls made through the MCP server require it.)

Beyond concurrency safeguards, the system also enforces data integrity. If an overwrite would orphan embedded attachments such as images or PDFs, bearcli aborts the operation and lists the affected files—requiring an explicit --force flag to proceed with destructive changes.

Ecosystem Rivalry: Defending Against Obsidian’s Local-First Wave

In the evolution of personal knowledge management, Obsidian redefined the landscape and applied relentless competitive pressure on Bear, a longtime favorite of the Apple ecosystem.

The Inherent Advantages of a Plain-Text Architecture

From day one, Obsidian stuck to an uncompromising principle: notes are simply plain-text Markdown files (Vaults) stored on your local disk. This philosophy resonated deeply with engineers and power users:

• Zero Vendor Lock-in: Notes are just standard directories and .md files. Even if the app is abandoned tomorrow, your data remains completely intact.
• First-Class Terminal Citizens: Search with rg, fuzzy-find with fzf, batch-edit with shell scripts, or run git init inside the vault for version control.
• A Native CLI and Plugin Ecosystem: Obsidian 1.12.7+ includes the official Obsidian CLI for searching, reading, creating, and modifying notes, while community REST APIs and plugins unlock additional integration scenarios.

By contrast, Bear excelled in Apple-native rendering, typographic finesse, and mobile responsiveness, but its proprietary SQLite backend and Apple-exclusive footprint felt restrictive to developers who demand full command over their environments. Community forums frequently voiced the same dilemma: engineers loved Bear’s design and feel, yet struggled to accept notes locked away from their terminal and automation tooling.

Shiny Frog’s Pragmatic Compromise

Faced with developer churn, Shiny Frog confronted a classic dilemma: rewriting the storage engine into flat Markdown files would deliver transparency, but at the cost of Bear’s fluid rich-text attachment handling, note encryption, efficient CloudKit delta syncing, and instant full-text search. Maintaining the status quo, however, meant risking irrelevance among technical users.

Shiny Frog opted for a pragmatic middle ground: preserve the polished SQLite/Core Data foundation under the hood, while exposing a modern CLI and secure broker layer that mirrors the plain-text experience. With bearcli, running bearcli search or bearcli cat feels remarkably close to rg and cat, bridging a longstanding automation gap.

AI Strategic Breakthrough: Native MCP Server and Tag Sandboxing

Closing the gap with terminal-first tools was only part of the motivation—the rapid ascent of AI agents was another key catalyst for Bear’s native CLI.

Why the Agent Era Demands MCP

Between 2024 and 2026, large language model applications evolved from conversational chatbots into autonomous AI agents capable of planning and invoking external tools (such as Claude Desktop, Claude Code, and Cursor). For knowledge workers, one of AI’s essential roles is to serve as an intelligent copilot for their personal note archives.

With a plain-text architecture, Obsidian is a natural playground for AI agents: they can mount vault directories directly as local workspaces, or search, read, and modify notes through the official Obsidian CLI.

That CLI connects to a running Obsidian desktop app, so it is not the same kind of interface as Bear’s MCP server. Still, without a structured, programmable interface of its own, Bear risked being sidelined from the personal knowledge assistant stack.

Key Architectural Features of bearcli mcp-server

bearcli natively supports Anthropic’s open standard, the Model Context Protocol (MCP). It embeds a fully functional MCP server communicating over standard input/output (stdio) via JSON-RPC 2.0:

bearcli mcp-server [--only-tags <tags>] [--exclude-tags <tags>]

This implementation incorporates three critical design choices:

1. Granular Tag Sandboxing (Tag Scoping): Privacy is the foremost concern when granting AI access to personal notes. Passing --only-tags dev,work restricts the AI strictly to notes bearing those tags and their nested sub-tags; any attempt to read personal journal entries immediately returns an out_of_scope error. Combined with --exclude-tags private, sensitive records remain entirely invisible to the model.
2. Intent Hints & Destructive Action Gates: Every tool exposed by the server declares readOnlyHint and destructiveHint metadata. Compatible clients use these hints to intercept calls to destructive endpoints like trash or overwrite, requiring explicit human confirmation before executing.
3. One-Click Claude Connector Setup: Bear’s macOS application menu now includes “Help -> Advanced -> Install Claude Connector.” Clicking it completes the MCP setup and mounting automatically within seconds—per Shiny Frog, no config files need to be edited by hand.

Practical Applications: High-Value Terminal Workflows from the Community

Since bearcli debuted, developer communities and open-source projects have established a range of high-leverage workflows.

Scenario 1: Seamless Context Retrieval in Claude Code and Cursor Workflows

When coding in the terminal, developers often need to consult internal Architecture Decision Records (ADRs) or environment setup notes previously documented in Bear. By adding an MCP declaration to the Claude Desktop config (claude_desktop_config.json) or a project-level .mcp.json:

{
  "mcpServers": {
    "bear-notes": {
      "command": "/Applications/Bear.app/Contents/MacOS/bearcli",
      "args": [
        "mcp-server",
        "--only-tags",
        "tech,dev,architecture"
      ]
    }
  }
}

In the terminal, the developer simply prompts Claude in natural language:

Search my Bear notes tagged #tech, find the staging environment Redis connection rules, and add them to the current .env.example.

Claude queries and retrieves the relevant note via MCP behind the scenes, eliminating the need to context-switch across windows or copy-paste text.

Scenario 2: Silent Quick Capture from the Shell

For capturing critical logs or command output in the terminal, or for quickly saving clipboard snippets into notes, lightweight shell functions enable instantaneous background capture:

# Quickly capture clipboard contents into Bear's scratchpad inbox
bclip() {
  local title="${1:-Clipboard Capture $(date '+%Y-%m-%d %H:%M')}"
  pbpaste | bearcli create "$title" --tags "inbox/quick" --content -
  echo "✓ Saved clipboard to Bear: $title"
}

# Append piped command output directly to a specific section in a note
bnote() {
  local title="$1" section="$2"
  bearcli append --title "$title" --section "$section" --content -
}

All operations execute silently in milliseconds without spawning GUI windows, preserving uninterrupted focus.

Scenario 3: Automated Daily Work Logs

Using macOS launchd or cron alongside Git history and bearcli, developers can automatically aggregate their daily output every evening:

#!/usr/bin/env bash
TODAY=$(date '+%Y-%m-%d')
NOTE_TITLE="Daily Log $TODAY"

# Ensure today's note exists
if ! bearcli search --query "@title \"$NOTE_TITLE\"" --count | grep -q "1"; then
  bearcli create "$NOTE_TITLE" --tags "journal/daily" \
    --content "# $NOTE_TITLE\n\n## Standup\n- [ ] Morning sync\n\n## Git Commits Today\n\n## Completed Tasks\n"
fi

# Collect all commits made today in the specified repository
COMMITS=$(git -C "$HOME/Projects/repo" log --since="midnight" --oneline --author="$(git config user.name)")
[ -n "$COMMITS" ] && bearcli append --title "$NOTE_TITLE" --section "## Git Commits Today" --content "$COMMITS"

Scenario 4: Notes as Code and Automated Linting

In the open-source ecosystem, projects like noxctl leverage bearcli as an underlying engine to put “Notes as Code” into practice.

A noxctl.toml declares the tag, master-note, and hub structure of the vault and idempotently converges it to that declared state—master and hub notes are generated automatically, and each managed note gets a canonical tag-line on top so bidirectional links come for free. Its audit/lint checks flag bad H1 titles, malformed canonical tag-lines, orphaned notes, and duplicate titles.

Similarly, BearKit (formerly bear-lint) traverses notes using bearcli cat --format json to flag dead links (wiki links targeting nonexistent notes) or malformed tags, applying batch fixes with bearcli overwrite guarded by --base hash receipts.

Evaluation and Decision Matrix: Bear + bearcli vs. Obsidian

bearcli is not an attempt to turn Bear into another Obsidian; rather, it provides the essential interoperability required in modern technical environments while preserving the application’s signature native craftsmanship.

Comprehensive Technical Comparison Matrix

Decision Guide for Technical Users

In today’s landscape, these tools serve fundamentally distinct profiles:

• Who should choose Bear + bearcli: Developers deeply invested in the Apple ecosystem who prioritize typographic elegance, native fluid micro-interactions, and frictionless quick capture; those previously turned off by the lack of automation or AI support; and power users leveraging AI agents like Claude who demand strict privacy protections through tag-sandboxed knowledge bases (--only-tags).
• Who should still choose Obsidian: Users whose daily environments span Linux or Windows, where cross-platform support is a hard requirement; those whose systems rely heavily on community plugins like Dataview, Canvas, or Excalidraw to build complex database workflows; and plain-text purists who refuse to store notes in anything other than raw, unmediated filesystem folders.

The arrival of bearcli and native MCP integration gives Apple-centric developers the best of both worlds: uncompromising native craftsmanship and the final missing piece of terminal and AI agent automation.