🐻

bearcli

The missing open-source CLI for Bear notes. Read, search, export, and manage your notes from the terminal.

✨ MCP + agent skill fuzzy search terminal UI markdown export git mirror secret redaction json/tsv output python library

View on GitHub Commands

bearcli

❯ bearcli list -n 3
╭──────────────────────────────────────┬────────────────────┬───────┬────────┬────────────╮
│ ID                                   │ Title              │ Tags  │ Status │ Modified   │
├──────────────────────────────────────┼────────────────────┼───────┼────────┼────────────┤
│ C44D09DC-7F0E-43BB-BEB8-67E3A389A448 │ bearcli fieldnotes │ notes │        │ 2026-07-27 │
│ 7766167B-A410-48A9-8F1A-FB66F2BD8FE4 │ TODO               │ work  │ pinned │ 2026-03-03 │
│ 4DE9B0D9-62FD-4462-A3DA-3D2AFF7AA1B4 │ Smarthome          │ home  │        │ 2026-07-26 │
╰──────────────────────────────────────┴────────────────────┴───────┴────────┴────────────╯

❯ bearcli search "quarterly planing" --fuzzy -n 1
╭───────┬──────────────────────────────────────┬──────────┬──────────────────────────╮
│ Score │ ID                                   │ Title    │ Match                    │
├───────┼──────────────────────────────────────┼──────────┼──────────────────────────┤
│    91 │ 2F148B6A-082E-4C3D-82A7-1D60A64BC3FD │ Planning │ …quarterly planning doc… │
╰───────┴──────────────────────────────────────┴──────────┴──────────────────────────╯

❯ bearcli export ~/bear-notes --sync --redact-secrets --push
Exported to ~/bear-notes: 3 written, 1919 unchanged, 2 secrets redacted, pushed

# uv add bearkit  (or: pip install bearkit)
from bearkit import Bear, BearWriteError

with Bear() as bear:
    for result in bear.search("quarterly planing", fuzzy=True)[:3]:
        print(f"{result.score:5.1f}  {result.note.title}")

    note = bear.get_note("c44d09dc")
    try:
        bear.add_tag(note, "reviewed")
        bear.open(note)
    except BearWriteError:
        print("Bear did not apply the change")

Install

❯ brew install michel-tricot/tap/bearcli # or: uv tool install bearcli, pipx install bearcli

Why `bearcli`

✨ Agent-ready

An Agent Skill for Claude Code. An MCP server for Claude Desktop, Cursor, and friends. bearcli mcp install wires up your client.

Fuzzy search

Typo-tolerant ranked search across titles, tags, and text. Plain substring matching by default.

Git backup & sync

--push mirrors your notes to a private repo. Only changed notes are rewritten. Every edit stays in history. Never gets stuck.

Secret protection

Exports are scanned for credentials first. Block, or redact with --redact-secrets. Fully offline.

Terminal UI

A full Bear client in your shell. Live-filtered list, inline markdown editing, tag autocompletion.

Scriptable

Every listing has json and tab-separated text output. Built for jq, cut, and pipes.

Open source

MIT licensed, end to end. Read the code, audit it, fork it. No black box between you and your notes.

Python library

The engine ships separately as bearkit. A typed Python API for reading, searching, writing, and secret scanning.

✨ For AI agents

bearcli ships an Agent Skill that teaches Claude Code how to drive the CLI. It also ships an MCP server (bearcli mcp run, stdio) for Claude Desktop, Cursor, VS Code, and friends. Note content is secret-redacted by default. Your agent can answer “what did I write about X?” straight from your notes.

❯ bearcli skills install

❯ bearcli mcp install # claude-desktop, claude-code, cursor, vscode, ...

Commands

Command	What it does
`bearcli skills list / show / install`	Bundled Agent Skill - inspect it, or install into an agent's skills directory
`bearcli mcp run / install`	MCP server (stdio) - serve notes to Claude Desktop, Cursor, and friends
`bearcli note list`	List notes with tag, date, and status filters
`bearcli note search`	Search titles, tags, and content - `--fuzzy` for typo tolerance
`bearcli note get`	Print a note's markdown, metadata, and attachment paths
`bearcli note create`	Create a note from arguments or stdin
`bearcli note append / replace / rename`	Edit an existing note
`bearcli note attach`	Add a file to a note
`bearcli note tag / untag`	Add or remove a tag on one note
`bearcli note trash / archive / open`	File a note away, or open it in Bear
`bearcli ui`	Bear in the terminal - search, edit, create, and tag notes
`bearcli stats`	Library statistics - counts, words, top tags, notes per year
`bearcli doctor`	Diagnose the setup - PATH conflicts, database access, MCP wiring
`bearcli tag list / rename / delete`	Manage tags across all notes
`bearcli export`	Export everything as browsable markdown folders - secret-scanned, and `--push` mirrors to a git repo

Install

Why bearcli

✨ Agent-ready

Fuzzy search

Git backup & sync

Secret protection

Terminal UI

Scriptable

Open source

Python library

✨ For AI agents

Commands

Why `bearcli`