🐻 bearcli
The missing open-source CLI for Bear notes. Read, search, export, and manage your notes from the terminal.
- ✨ Agent-ready - bundled Claude skill and MCP server (
bearcli mcp install) - Search & browse - fuzzy or exact, filters for tags, dates, and status
- Write - create, append, tag, archive, straight from the terminal
- Terminal UI - a full Bear client in your shell
- Export & git mirror - self-contained markdown folders, never-stuck
--push - Secret protection - offline credential scanning and redaction
- Scriptable - JSON/TSV output everywhere; Python API via
bearkit
Install
brew install michel-tricot/tap/bearcli # or: uv tool install bearcli, pipx install bearcli
Or from a clone: uv sync, then uv run bearcli --help.
Troubleshooting
bearcli doctor checks the whole setup: which binary your PATH picks up,
Bear app presence, database access, and MCP client wiring — with a fix
suggested for anything it flags.
The bearcli command can conflict with Bear's official CLI if both are
installed — which -a bearcli shows which one your shell picks. To make
this CLI take precedence, put its install directory first in your PATH:
# in your ~/.zshrc or ~/.bashrc
export PATH="$(brew --prefix)/bin:$PATH" # brew install
export PATH="$HOME/.local/bin:$PATH" # uv tool or pipx install
MCP configs are immune to the conflict: bearcli mcp install writes the
absolute path of the very binary it is run from. If bearcli itself
reaches the wrong tool, call ours by its full path once:
"$(brew --prefix)/bin/bearcli" mcp install # or: ~/.local/bin/bearcli
Quick start
bearcli list # 20 most recently modified notes
bearcli search "quarterly report" # search titles, tags, and content
bearcli get <note-id> # print a note's markdown
bearcli create "Idea" --tag inbox # create a note
bearcli export ~/bear-backup # export everything as markdown folders
bearcli ui # full Bear client in the terminal
Commands
Commands are grouped under note and tag.
Shortcuts
The most common commands are also top-level aliases:
bearcli list # alias for `note list`
bearcli search # alias for `note search`
bearcli get # alias for `note get`
bearcli open # alias for `note open`
bearcli create # alias for `note create`
Browse & read
bearcli note list # 20 most recently modified
bearcli note list --limit 5 --tag work # filters: tag (incl. nested), dates...
bearcli note list --modified-after 2026-07-01
bearcli note list --only pinned # or: encrypted, trashed, archived
bearcli note list --all --trashed --archived
bearcli note list --ids # only identifiers, one per line
bearcli note get C44D09DC # a unique id prefix (4+ chars) works everywhere
bearcli note get C44D09DC-... --meta # with YAML-style frontmatter
bearcli note get C44D09DC-... -r # rewrite attachment refs to absolute paths
bearcli note get C44D09DC-... --redact-secrets # secrets replaced by placeholders
bearcli note open C44D09DC-... # open in the Bear app
Search
bearcli note search "invoice" --tag work -n 5 # case-insensitive substring
bearcli note search "quarterly planing" --fuzzy # typo-tolerant, ranked by score
Write
Writes go through the Bear app and are verified before the command reports success.
bearcli note create "Meeting notes" --text "agenda..." --tag work
echo "follow-up item" | bearcli note append C44D09DC-...
bearcli note rename C44D09DC-... "New title"
bearcli note get C44D09DC-... | sed 's/foo/bar/' | bearcli note replace C44D09DC-...
bearcli note attach C44D09DC-... screenshot.png # ≤500 KB
bearcli note archive C44D09DC-...
bearcli note trash C44D09DC-...
Tags
bearcli tag list # all tags with note counts
bearcli note tag C44D09DC-... "work/ideas" # add a tag to a note
bearcli note untag C44D09DC-... "work/ideas" # remove a tag from a note
bearcli tag rename old-name new-name # across all notes
bearcli tag delete old-name # across all notes (asks first)
Export
Every note becomes a directory: <slug>/README.md plus attachments. A
generated index makes the export browsable on GitHub.
Notes are scanned for secrets before anything is written. Findings block
the export. Use --redact-secrets to export with [redacted: <rule>]
placeholders or --allow-secrets to export as-is. Notes in Bear are never
modified.
⚠️ Warning: detection is best-effort. A secret that reads like ordinary text will not be caught. Better: keep secrets in a password manager or in Bear's encrypted notes.
bearcli export ~/bear-backup
bearcli export ~/bear-backup --sync # only rewrite notes that changed
bearcli export ~/bear-backup --redact-secrets # secrets become [redacted: <rule>]
# Mirror to a private git repo (clone it first). Bear is the source of truth:
# manual edits stay in history but HEAD always matches Bear. Never gets stuck.
git clone git@github.com:you/bear-notes.git ~/bear-notes
bearcli export ~/bear-notes --sync --push
Terminal UI
bearcli ui is a full Bear client in the terminal. Press ? for the key map.
Scripting
Every listing takes --format / -f: table (default), json, or
tab-separated text built for pipes.
bearcli list -f json | jq -r '.[].title'
bearcli list -f text | cut -f1 # text is: id, modified, tags, status, title
bearcli stats -f json # library totals: counts, words, top tags
Dates are ISO (2026-07-01 or 2026-07-01T14:30). Override the database
path with --db or BEAR_DB_PATH. Encrypted notes are listed but
unreadable. bearcli --version prints the version.
Agent skill
An Agent Skill for Claude Code and other agents ships inside the package (source):
bearcli skills install # into ~/.claude/skills/
bearcli skills install --dir .claude/skills # into a project
bearcli skills list # bundled skills
bearcli skills show bear-notes # print the skill
Reinstall after upgrading so agents always match the installed CLI.
MCP server
bearcli mcp run serves your notes to AI apps over MCP (stdio): list,
read, search, create, edit, tag, archive, open in Bear. Note content is
secret-redacted by default.
bearcli mcp install configures your client:
bearcli mcp install # choose from a list
bearcli mcp install claude-desktop # or: claude-code, cursor, vscode,
# windsurf, gemini-cli, zed, codex
JSON configs are updated in place with a .bak. Other clients get exact
instructions. Restart the client afterwards.
Use as a library
The engine ships separately on PyPI as bearkit: reading, search, writes,
and secret detection. No CLI or TUI dependencies.
from bearkit import Bear, BearWriteError
with Bear() as bear:
for note in bear.list_notes(tag="work", limit=10):
print(note.title, note.tags)
try:
bear.add_tag(bear.get_note("C44D09DC"), "from-python")
except BearWriteError:
print("Bear did not apply the change")
Full reference: docs/BEARKIT.md. The package ships typed
(py.typed).
Development
uv sync
uv run ruff format src/ && uv run ruff check src/
uv run ty check src/
uv run python scripts/check_docs.py # docs must cover every command
Design notes and internals: docs/IMPLEMENTATION.md. Contributor/agent guidelines: AGENTS.md.
License
MIT · not affiliated with Shiny Frog
Metadata
Release files for bearcli 1.7.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bearcli-1.7.6.tar.gz | 33.4 kB | Without provenance | Details for bearcli-1.7.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bearcli-1.7.6-py3-none-any.whl | Python 3 | none | any | Details for bearcli-1.7.6-py3-none-any.whl |
Total release size: 75.5 kB
Release files / bearcli-1.7.6.tar.gz
| Download URL | bearcli-1.7.6.tar.gz |
|---|---|
| Size | 33.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
697b322f17e759a93292dd9e18066a4fb4ad0fcc843a2289073aa94307cbb1e4
|
|
BLAKE2b-256 checksum How to use checksums |
05f73fb37268d12f2a3bafb89b2d3f8a1d101237b524e14e8954e17271cc70b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / bearcli-1.7.6-py3-none-any.whl
| Download URL | bearcli-1.7.6-py3-none-any.whl |
|---|---|
| Size | 42.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3be2176229536808b9780abb86641e0735432b8c45483b6556e84ef23a061502
|
|
BLAKE2b-256 checksum How to use checksums |
69001ca88f116a49f49e01ef63bdc4329491eb5daa4041cdc01ca29dd27cd0f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for bearcli 1.7.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.