Install

uv tool install bearcli        # or: uvx bearcli, pipx install bearcli
brew install michel-tricot/tap/bearcli   # or via Homebrew

Or from a clone: uv sync, then uv run bearcli --help.

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; the most common ones (list, search, get, open, create) also work directly as shortcuts.

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 get C44D09DC       # a unique id prefix (4+ chars) works everywhere
bearcli get C44D09DC-... --meta              # with YAML-style frontmatter
bearcli get C44D09DC-... -r                  # rewrite attachment refs to absolute paths
bearcli get C44D09DC-... --redact-secrets    # secrets replaced by placeholders
bearcli open C44D09DC-...                    # open in the Bear app
bearcli ui                                   # Bear in the terminal: search, edit, tag
bearcli stats                                # counts, words, top tags, notes per year

Terminal UI

bearcli ui is a full Bear client in the terminal: the note list with live filtering on the left, markdown preview and inline editor on the right. / search - enter/e edit (ctrl+s saves, with an unsaved-changes guard) - n/c new note - t/T tag/untag - o open in Bear - a archive - d trash - 1/2/3 notes/archive/trash views - j/k navigation - ? shows the full key map. Notes with detected secrets get a red title, a 🚨 badge, and the secret values highlighted in the preview and editor; encrypted notes show 🔒 and keep their content in Bear.

Search

bearcli search "invoice" --tag work -n 5     # case-insensitive substring
bearcli search "quarterly planing" --fuzzy   # typo-tolerant, ranked by score

Write

Writes go through the Bear app itself (launching it if needed), and every change is verified before the command reports success.

bearcli create "Meeting notes" --text "agenda..." --tag work
echo "follow-up item" | bearcli note append C44D09DC-...
bearcli note rename C44D09DC-... "New title"
bearcli 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 self-contained directory - <slug>/README.md plus its attachments - with a generated index, so GitHub renders the whole export as a browsable tree.

Before anything is written, the notes are scanned for potential secrets (token formats, key blocks, credential assignments, high-entropy strings); findings block the export with a list of the affected notes. Override with --allow-secrets (export as-is) or --redact-secrets (replace each secret with a [redacted: <rule>] placeholder - notes in Bear are untouched).

⚠️ Warning - detection and redaction are best-effort: a secret that reads like ordinary text (a password written as prose, an account number) will not be caught. Ideally, don't keep secrets in notes at all - use a password manager, or at least Bear's encrypted notes, which never leave the app.

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 git repository (clone it first; use a *private* repo - these are
# your notes). Bear is the source of truth: remote or manual edits are kept in
# git history but overwritten in HEAD. Never force-pushes, never gets stuck.
git clone git@github.com:you/bear-notes.git ~/bear-notes
bearcli export ~/bear-notes --sync --push

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

Dates use ISO format (2026-07-01 or 2026-07-01T14:30). The database path defaults to Bear's standard location and can be overridden with --db or the BEAR_DB_PATH environment variable. Encrypted notes are listed but their content cannot be read.

Agent skill

An Agent Skill teaching AI agents (Claude Code, etc.) how to use bearcli ships in skills/bear-notes:

cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/

Use as a library

The fundamentals ship as their own package on PyPI, bearkit - reading notes, verified writes, search, and secret detection - with no CLI or TUI dependencies (pip install bearkit):

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