bearcli 1.6.3__tar.gz → 1.7.0__tar.gz

{bearcli-1.6.3 → bearcli-1.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: bearcli
-Version: 1.6.3
-Summary: The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal
+Version: 1.7.0
+Summary: The missing open-source CLI for Bear notes - read, search, export, and manage your notes from the terminal
 Keywords: bear,notes,cli,markdown,macos
 Author: Michel Tricot
 Author-email: Michel Tricot <michel.tricot@gmail.com>
@@ -12,7 +12,8 @@ Classifier: Environment :: Console
 Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
-Requires-Dist: bearkit==1.6.3
+Requires-Dist: bearkit==1.7.0
+Requires-Dist: fastmcp>=3.4.5
 Requires-Dist: textual>=8.2.8
 Requires-Dist: typer>=0.27.0
 Requires-Python: >=3.13
@@ -25,8 +26,8 @@ Description-Content-Type: text/markdown
 
 # 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** - read, search, export, and
-manage your notes from the terminal.
+**The missing open-source CLI for [Bear](https://bear.app) notes.**
+Read, search, export, and manage your notes from the terminal.
 
 [![CI](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml/badge.svg)](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -41,6 +42,14 @@ 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`](https://pypi.org/project/bearkit/)
+
 ## Install
 
 ```sh
@@ -62,53 +71,42 @@ 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.
+Commands are grouped under `note` and `tag`.
 
 ### Browse & read
 
 ```sh
 bearcli note list                            # 20 most recently modified
+bearcli list                                 # shortcut for `note list`
 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       # shortcut for `note get`; 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 open C44D09DC-...                    # open in the Bear app (shortcut for `note open`)
 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
 
 ```sh
-bearcli search "invoice" --tag work -n 5     # case-insensitive substring
+bearcli search "invoice" --tag work -n 5     # case-insensitive substring (shortcut for `note search`)
 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.
+Writes go through the Bear app and are verified before the command reports
+success.
 
 ```sh
-bearcli create "Meeting notes" --text "agenda..." --tag work
+bearcli create "Meeting notes" --text "agenda..." --tag work   # shortcut for `note create`
 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-...
@@ -129,34 +127,35 @@ 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.
+Every note becomes a directory: `<slug>/README.md` plus attachments. A
+generated index makes the export browsable on GitHub.
 
-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).
+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 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.
+> **⚠️ 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.
 
 ```sh
 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.
+# 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.
+
+![bearcli ui](https://raw.githubusercontent.com/michel-tricot/bearcli/main/docs/tui.svg)
+
 ## Scripting
 
 Every listing takes `--format` / `-f`: `table` (default), `json`, or
@@ -167,26 +166,46 @@ 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.
+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](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
-teaching AI agents (Claude Code, etc.) how to use `bearcli` ships in
-[`skills/bear-notes`](skills/bear-notes/SKILL.md):
+for Claude Code and other agents ships inside the package
+([source](src/bearcli/skills/bear-notes/SKILL.md)):
 
 ```sh
-cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+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:
+
+```sh
+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 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`):
+The engine ships separately on PyPI as `bearkit`: reading, search, writes,
+and secret detection. No CLI or TUI dependencies.
 
 ```python
 from bearkit import Bear, BearWriteError

{bearcli-1.6.3 → bearcli-1.7.0}/README.md

@@ -2,8 +2,8 @@
 
 # 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** - read, search, export, and
-manage your notes from the terminal.
+**The missing open-source CLI for [Bear](https://bear.app) notes.**
+Read, search, export, and manage your notes from the terminal.
 
 [![CI](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml/badge.svg)](https://github.com/michel-tricot/bearcli/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -18,6 +18,14 @@ 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`](https://pypi.org/project/bearkit/)
+
 ## Install
 
 ```sh
@@ -39,53 +47,42 @@ 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.
+Commands are grouped under `note` and `tag`.
 
 ### Browse & read
 
 ```sh
 bearcli note list                            # 20 most recently modified
+bearcli list                                 # shortcut for `note list`
 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       # shortcut for `note get`; 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 open C44D09DC-...                    # open in the Bear app (shortcut for `note open`)
 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
 
 ```sh
-bearcli search "invoice" --tag work -n 5     # case-insensitive substring
+bearcli search "invoice" --tag work -n 5     # case-insensitive substring (shortcut for `note search`)
 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.
+Writes go through the Bear app and are verified before the command reports
+success.
 
 ```sh
-bearcli create "Meeting notes" --text "agenda..." --tag work
+bearcli create "Meeting notes" --text "agenda..." --tag work   # shortcut for `note create`
 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-...
@@ -106,34 +103,35 @@ 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.
+Every note becomes a directory: `<slug>/README.md` plus attachments. A
+generated index makes the export browsable on GitHub.
 
-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).
+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 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.
+> **⚠️ 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.
 
 ```sh
 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.
+# 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.
+
+![bearcli ui](https://raw.githubusercontent.com/michel-tricot/bearcli/main/docs/tui.svg)
+
 ## Scripting
 
 Every listing takes `--format` / `-f`: `table` (default), `json`, or
@@ -144,26 +142,46 @@ 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.
+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](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
-teaching AI agents (Claude Code, etc.) how to use `bearcli` ships in
-[`skills/bear-notes`](skills/bear-notes/SKILL.md):
+for Claude Code and other agents ships inside the package
+([source](src/bearcli/skills/bear-notes/SKILL.md)):
 
 ```sh
-cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+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:
+
+```sh
+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 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`):
+The engine ships separately on PyPI as `bearkit`: reading, search, writes,
+and secret detection. No CLI or TUI dependencies.
 
 ```python
 from bearkit import Bear, BearWriteError

{bearcli-1.6.3 → bearcli-1.7.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "bearcli"
-version = "1.6.3"
-description = "The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal"
+version = "1.7.0"
+description = "The missing open-source CLI for Bear notes - read, search, export, and manage your notes from the terminal"
 readme = "README.md"
 keywords = ["bear", "notes", "cli", "markdown", "macos"]
 classifiers = [
@@ -18,7 +18,8 @@ license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.13"
 dependencies = [
-    "bearkit==1.6.3",
+    "bearkit==1.7.0",
+    "fastmcp>=3.4.5",
     "textual>=8.2.8",
     "typer>=0.27.0",
 ]

{bearcli-1.6.3 → bearcli-1.7.0}/src/bearcli/cli/__init__.py

@@ -2,7 +2,6 @@
 
 from collections.abc import Callable
 
-from bearcli.cli import export, misc, notes, tags  # noqa: F401  # command registration
 from bearcli.cli.common import app
 from bearcli.cli.notes import create, get, list_notes, open_note, search
 
@@ -22,4 +21,8 @@ _alias("open", "note open", open_note)
 
 _alias("create", "note create", create)
 
+# Imported after the aliases: help panels render in registration order, and
+# Shortcuts should lead the top-level help.
+from bearcli.cli import export, mcp, misc, skills, tags  # noqa: E402, F401  # command registration
+
 __all__ = ["app"]

{bearcli-1.6.3 → bearcli-1.7.0}/src/bearcli/cli/common.py

@@ -5,24 +5,62 @@ from __future__ import annotations
 import sys
 from datetime import datetime
 from enum import StrEnum
+from importlib.metadata import version
 from pathlib import Path
 from typing import Annotated
 
 import typer
 from rich.console import Console
+from typer.core import TyperGroup
 
 from bearkit import Bear
 from bearkit.db import AmbiguousNoteId, Note, NoteFilter
 
-app = typer.Typer(help="Read notes from the Bear note app.", no_args_is_help=True, add_completion=False)
+
+class _GoodiesLast(TyperGroup):
+    """Help panels render in command order; sort Goodies to the end."""
+
+    def list_commands(self, ctx):
+        names = super().list_commands(ctx)
+        return sorted(names, key=lambda n: getattr(self.commands[n], "rich_help_panel", "") == "Goodies")
+
+
+app = typer.Typer(
+    cls=_GoodiesLast, help="Read notes from the Bear note app.", no_args_is_help=True, add_completion=False
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        print(f"bearcli {version('bearcli')} (bearkit {version('bearkit')})")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    show_version: Annotated[
+        bool,
+        typer.Option("--version", callback=_print_version, is_eager=True, help="Print the version and exit."),
+    ] = False,
+) -> None:
+    pass
+
 
 note_app = typer.Typer(help="Create, read, and modify notes.", no_args_is_help=True)
 
 tag_app = typer.Typer(help="List and manage tags.", no_args_is_help=True)
 
-app.add_typer(note_app, name="note")
+skills_app = typer.Typer(help="Agent skills bundled with bearcli.", no_args_is_help=True)
+
+mcp_app = typer.Typer(help="MCP server for AI apps (Claude Desktop, Claude Code, ...).", no_args_is_help=True)
+
+app.add_typer(note_app, name="note", rich_help_panel="Notes & tags")
+
+app.add_typer(tag_app, name="tag", rich_help_panel="Notes & tags")
+
+app.add_typer(skills_app, name="skills", rich_help_panel="Agents")
 
-app.add_typer(tag_app, name="tag")
+app.add_typer(mcp_app, name="mcp", rich_help_panel="Agents")
 
 console = Console()
 

{bearcli-1.6.3 → bearcli-1.7.0}/src/bearcli/cli/export.py

@@ -40,7 +40,7 @@ def _report_secrets(findings: list[SecretFinding]) -> None:
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Notes & tags")
 def export(
     dest: Annotated[Path, typer.Argument(help="Destination directory for the markdown files.")],
     sync: Annotated[

bearcli-1.7.0/src/bearcli/cli/mcp.py

@@ -0,0 +1,171 @@
+"""MCP commands (the `mcp` group): run the server, install it into clients."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from bearcli.cli.common import DbPathOption, _open_bear, console, mcp_app
+from bearkit.db import DEFAULT_DB_PATH
+
+
+@mcp_app.command()
+def run(
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Serve notes to AI apps over MCP (stdio only). Started by the client, not by hand."""
+    from bearcli.mcpserver import run as run_server
+
+    _open_bear(db_path).close()  # fail fast with a clear message if the db is missing
+    run_server(db_path)
+
+
+def _bearcli_command() -> str:
+    return shutil.which("bearcli") or sys.argv[0] or "bearcli"
+
+
+@dataclass(frozen=True)
+class Client:
+    key: str
+    label: str
+    config_path: str | None = None  # JSON config to update (relative to home); None: no file edit
+    servers_key: str = "mcpServers"
+    entry_extra: tuple[tuple[str, str], ...] = ()  # extra fields some clients want
+    manual: str | None = None  # instructions when we cannot (or should not) edit config
+
+
+def _clients() -> list[Client]:
+    command = _bearcli_command()
+    return [
+        Client(
+            key="claude-code",
+            label="Claude Code",
+            manual=f"claude mcp add --scope user bear -- {command} mcp run",
+        ),
+        Client(
+            key="claude-desktop",
+            label="Claude Desktop",
+            config_path="Library/Application Support/Claude/claude_desktop_config.json",
+        ),
+        Client(key="cursor", label="Cursor", config_path=".cursor/mcp.json"),
+        Client(
+            key="vscode",
+            label="VS Code (Copilot)",
+            config_path="Library/Application Support/Code/User/mcp.json",
+            servers_key="servers",
+            entry_extra=(("type", "stdio"),),
+        ),
+        Client(key="windsurf", label="Windsurf", config_path=".codeium/windsurf/mcp_config.json"),
+        Client(key="gemini-cli", label="Gemini CLI", config_path=".gemini/settings.json"),
+        Client(
+            key="zed",
+            label="Zed",
+            manual=(
+                "Add to ~/.config/zed/settings.json:\n"
+                f'  "context_servers": {{\n'
+                f'    "bear": {{ "command": {{ "path": "{command}", "args": ["mcp", "run"] }} }}\n'
+                f"  }}"
+            ),
+        ),
+        Client(
+            key="codex",
+            label="Codex CLI",
+            manual=(
+                f'Add to ~/.codex/config.toml:\n  [mcp_servers.bear]\n  command = "{command}"\n  args = ["mcp", "run"]'
+            ),
+        ),
+    ]
+
+
+def _entry(client: Client) -> dict:
+    return dict(client.entry_extra) | {"command": _bearcli_command(), "args": ["mcp", "run"]}
+
+
+def _install_into_json(client: Client) -> None:
+    path = Path.home() / str(client.config_path)
+    config: dict = {}
+    if path.exists():
+        try:
+            config = json.loads(path.read_text() or "{}")
+        except json.JSONDecodeError as exc:
+            console.print(f"[red]Error:[/red] could not parse {path} ({exc}); add this entry manually:")
+            print(json.dumps({client.servers_key: {"bear": _entry(client)}}, indent=2))
+            raise typer.Exit(1) from None
+        shutil.copy2(path, path.with_name(path.name + ".bak"))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    config.setdefault(client.servers_key, {})["bear"] = _entry(client)
+    path.write_text(json.dumps(config, indent=2) + "\n")
+    console.print(f"Added the 'bear' MCP server to {client.label}: {path}")
+    console.print(f"Restart {client.label} to pick it up.")
+
+
+def _run_claude_code(client: Client) -> None:
+    command = _bearcli_command()
+    if shutil.which("claude") is None:
+        console.print("Claude Code's `claude` CLI is not on PATH; run this once it is:")
+        print(client.manual)
+        return
+    result = subprocess.run(
+        ["claude", "mcp", "add", "--scope", "user", "bear", "--", command, "mcp", "run"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        console.print(f"[red]Error:[/red] `claude mcp add` failed:\n{result.stderr.strip()}")
+        raise typer.Exit(1)
+    console.print("Added the 'bear' MCP server to Claude Code (user scope).")
+
+
+def _pick_client(clients: list[Client]) -> Client:
+    console.print("Which MCP client should use bearcli?\n")
+    for i, c in enumerate(clients, start=1):
+        console.print(f"  {i}. {c.label}")
+    console.print()
+    choice = typer.prompt("Number")
+    try:
+        return clients[int(choice) - 1]
+    except (ValueError, IndexError):
+        console.print(f"[red]Error:[/red] pick a number between 1 and {len(clients)}")
+        raise typer.Exit(2) from None
+
+
+@mcp_app.command()
+def install(
+    client_key: Annotated[
+        str | None,
+        typer.Argument(
+            help="MCP client to configure (claude-code, claude-desktop, cursor, vscode, "
+            "windsurf, gemini-cli, zed, codex). Omit to choose interactively."
+        ),
+    ] = None,
+) -> None:
+    """Configure an MCP client to use bearcli (updates its config, or shows how)."""
+    clients = _clients()
+    if client_key is None:
+        if not sys.stdin.isatty():
+            console.print("[red]Error:[/red] no terminal to ask in; pass a client, e.g. `bearcli mcp install cursor`")
+            raise typer.Exit(2)
+        client = _pick_client(clients)
+    else:
+        match = next((c for c in clients if c.key == client_key.lower()), None)
+        if match is None:
+            console.print(
+                f"[red]Error:[/red] unknown client {client_key!r}; one of: {', '.join(c.key for c in clients)}"
+            )
+            raise typer.Exit(2)
+        client = match
+
+    if client.key == "claude-code":
+        _run_claude_code(client)
+    elif client.config_path is not None:
+        _install_into_json(client)
+    else:
+        console.print(f"To wire bearcli into {client.label}:\n")
+        print(client.manual)

{bearcli-1.6.3 → bearcli-1.7.0}/src/bearcli/cli/misc.py

@@ -19,7 +19,7 @@ from bearcli.cli.common import (
 from bearkit.db import DEFAULT_DB_PATH
 
 
-@app.command()
+@app.command(rich_help_panel="Goodies")
 def stats(
     fmt: Annotated[
         OutputFormat,
@@ -92,7 +92,7 @@ def stats(
     console.print(year_table)
 
 
-@app.command()
+@app.command(rich_help_panel="Goodies")
 def ui(
     fuzzy: Annotated[bool, typer.Option("--fuzzy", help="Typo-tolerant ranked filtering.")] = False,
     tag_filter: Annotated[str | None, typer.Option("--tag", "-t", help="Restrict to notes with this tag.")] = None,

{bearcli-1.6.3 → bearcli-1.7.0}/src/bearcli/cli/notes.py

@@ -35,7 +35,7 @@ def _resolve_attachments(note: Note) -> str:
     return rewrite_attachment_refs(note, lambda att: str(att.path))
 
 
-@note_app.command("list")
+@note_app.command("list", rich_help_panel="Read")
 def list_notes(
     limit: Annotated[int, typer.Option("--limit", "-n", help="Maximum number of notes.")] = 20,
     tag: Annotated[
@@ -122,7 +122,7 @@ def list_notes(
     console.print(table)
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Read")
 def get(
     note_id: Annotated[str, typer.Argument(help="Note identifier (UUID from `bearcli list`).")],
     meta: Annotated[bool, typer.Option("--meta", help="Print metadata frontmatter before the content.")] = False,
@@ -222,7 +222,7 @@ def _create_and_perform(bear: Bear, title: str, text: str | None, tags: list[str
     console.print(f"Created note {created.id}")
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Write")
 def create(
     title: Annotated[str, typer.Argument(help="Title of the new note.")],
     text: Annotated[str | None, typer.Option("--text", help="Note body (reads stdin if piped).")] = None,
@@ -237,7 +237,7 @@ def create(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Write")
 def append(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     text: Annotated[str | None, typer.Option("--text", help="Text to add (reads stdin if piped).")] = None,
@@ -261,7 +261,7 @@ def append(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Organize")
 def trash(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     db_path: DbPathOption = DEFAULT_DB_PATH,
@@ -278,7 +278,7 @@ def trash(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Organize")
 def archive(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     db_path: DbPathOption = DEFAULT_DB_PATH,
@@ -295,7 +295,7 @@ def archive(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Organize")
 def tag(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     name: Annotated[str, typer.Argument(help="Tag to add (without the leading #).")],
@@ -317,7 +317,7 @@ def tag(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Organize")
 def untag(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     name: Annotated[str, typer.Argument(help="Tag to remove (without the leading #).")],
@@ -345,7 +345,7 @@ def untag(
         bear.close()
 
 
-@note_app.command("open")
+@note_app.command("open", rich_help_panel="Read")
 def open_note(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     new_window: Annotated[bool, typer.Option("--new-window", "-w", help="Open in a separate window.")] = False,
@@ -364,7 +364,7 @@ def open_note(
 MAX_ATTACH_BYTES = 500_000  # the file travels base64-encoded inside a URL; macOS caps arg size at ~1 MB
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Write")
 def attach(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     file: Annotated[Path, typer.Argument(help="File to attach (appended at the end of the note).")],
@@ -393,7 +393,7 @@ def attach(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Write")
 def rename(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     new_title: Annotated[str, typer.Argument(help="New title for the note.")],
@@ -415,7 +415,7 @@ def rename(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Write")
 def replace(
     note_id: Annotated[str, typer.Argument(help="Note identifier.")],
     text: Annotated[str | None, typer.Option("--text", help="New body (reads stdin if piped).")] = None,
@@ -438,7 +438,7 @@ def replace(
         bear.close()
 
 
-@note_app.command()
+@note_app.command(rich_help_panel="Read")
 def search(
     query: Annotated[str, typer.Argument(help="Search terms, matched against titles, tags, and text.")],
     fuzzy: Annotated[bool, typer.Option("--fuzzy", help="Typo-tolerant matching, ranked by score.")] = False,

bearcli-1.7.0/src/bearcli/cli/skills.py

@@ -0,0 +1,67 @@
+"""Agent-skill commands (the `skills` group)."""
+
+from __future__ import annotations
+
+import shutil
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from bearcli.cli.common import console, skills_app
+
+DEFAULT_SKILLS_DIR = Path.home() / ".claude" / "skills"
+
+
+def _skill_dirs() -> dict[str, Path]:
+    root = Path(str(files("bearcli") / "skills"))
+    return {d.name: d for d in sorted(root.iterdir()) if (d / "SKILL.md").is_file()}
+
+
+def _description(skill_dir: Path) -> str:
+    for line in (skill_dir / "SKILL.md").read_text().splitlines():
+        if line.startswith("description:"):
+            return line.removeprefix("description:").strip()
+    return ""
+
+
+def _resolve(name: str | None) -> Path:
+    skills = _skill_dirs()
+    if name is None and len(skills) == 1:
+        return next(iter(skills.values()))
+    if name in skills:
+        return skills[name]
+    console.print(f"[red]Error:[/red] unknown skill {name!r}; available: {', '.join(skills)}")
+    raise typer.Exit(1)
+
+
+@skills_app.command("list")
+def list_skills() -> None:
+    """List the agent skills bundled with bearcli."""
+    for name, skill_dir in _skill_dirs().items():
+        print(f"{name}\t{_description(skill_dir)}")
+
+
+@skills_app.command()
+def show(
+    name: Annotated[str | None, typer.Argument(help="Skill name (optional when only one ships).")] = None,
+) -> None:
+    """Print a skill's SKILL.md to stdout."""
+    print((_resolve(name) / "SKILL.md").read_text(), end="")
+
+
+@skills_app.command()
+def install(
+    name: Annotated[str | None, typer.Argument(help="Skill name (optional when only one ships).")] = None,
+    directory: Annotated[
+        Path,
+        typer.Option("--dir", help="Skills directory to install into (e.g. a project's .claude/skills)."),
+    ] = DEFAULT_SKILLS_DIR,
+) -> None:
+    """Install a skill into an agent's skills directory (overwrites an older copy)."""
+    source = _resolve(name)
+    target = directory / source.name
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, target, dirs_exist_ok=True)
+    console.print(f"Installed skill {source.name!r} to {target}")

bearcli-1.7.0/src/bearcli/mcpserver.py

@@ -0,0 +1,160 @@
+"""FastMCP server exposing Bear notes to AI apps (the `mcp` command). Stdio only.
+
+Every tool opens a fresh connection so long-running sessions always see
+current data. Note text returned to the model is secret-redacted by default:
+MCP clients ship tool results to their model provider, so raw credentials
+must not travel unless the user explicitly turns redaction off.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from bearkit import Bear, TextMode, scan_notes
+from bearkit.db import DEFAULT_DB_PATH, Note
+
+
+def _summary(note: Note) -> dict:
+    return note.to_dict()
+
+
+def _redacted_text(note: Note, redact: bool) -> str | None:
+    if note.text is None:
+        return None
+    return scan_notes([note]).redact_text(note.text) if redact else note.text
+
+
+def _require(bear: Bear, note_id: str) -> Note:
+    note = bear.get_note(note_id)
+    if note is None:
+        raise ValueError(f"no note with id {note_id!r}")
+    return note
+
+
+def build_server(db_path: Path = DEFAULT_DB_PATH) -> FastMCP:
+    server = FastMCP(
+        name="bearcli",
+        instructions=(
+            "Read, search, and manage the user's Bear notes. Note ids accept unique "
+            "prefixes of 4+ characters. Writes go through the Bear app and are "
+            "verified; they fail if Bear cannot run. Encrypted notes have no "
+            "readable text."
+        ),
+    )
+
+    @server.tool
+    def list_notes(
+        limit: int = 20,
+        tag: str | None = None,
+        only: str | None = None,
+        include_trashed: bool = False,
+        include_archived: bool = False,
+    ) -> list[dict]:
+        """List notes (metadata only), most recently modified first.
+
+        `tag` includes nested sub-tags; `only` filters to one status:
+        pinned, encrypted, trashed, or archived.
+        """
+        with Bear(db_path) as bear:
+            return [
+                _summary(n)
+                for n in bear.list_notes(
+                    limit=limit,
+                    tag=tag,
+                    only=only,
+                    include_trashed=include_trashed,
+                    include_archived=include_archived,
+                )
+            ]
+
+    @server.tool
+    def get_note(note_id: str, redact_secrets: bool = True) -> dict:
+        """Fetch one note: metadata plus its markdown text.
+
+        Detected secrets are replaced with [redacted: <rule>] placeholders
+        unless redact_secrets is false (only disable when the user explicitly
+        wants raw credential values).
+        """
+        with Bear(db_path) as bear:
+            note = _require(bear, note_id)
+            return {**_summary(note), "text": _redacted_text(note, redact_secrets)}
+
+    @server.tool
+    def search_notes(query: str, fuzzy: bool = False, tag: str | None = None, limit: int = 10) -> list[dict]:
+        """Search titles, tags, and content; fuzzy is typo-tolerant and adds a score."""
+        with Bear(db_path) as bear:
+            results = bear.search(query, fuzzy=fuzzy, tag=tag)[:limit]
+            return [
+                {**_summary(r.note), "snippet": r.snippet} | ({"score": r.score} if r.score is not None else {})
+                for r in results
+            ]
+
+    @server.tool
+    def list_tags() -> list[dict]:
+        """All tags with their note counts."""
+        with Bear(db_path) as bear:
+            return [{"tag": t, "notes": c} for t, c in bear.list_tags()]
+
+    @server.tool
+    def create_note(title: str, text: str | None = None, tags: list[str] | None = None) -> dict:
+        """Create a note; returns it (with its new id) once Bear confirms."""
+        with Bear(db_path) as bear:
+            return _summary(bear.create_note(title, text, tags))
+
+    @server.tool
+    def append_to_note(note_id: str, text: str, prepend: bool = False) -> dict:
+        """Append (or prepend) text to a note; returns the updated note."""
+        with Bear(db_path) as bear:
+            note = _require(bear, note_id)
+            mode = TextMode.PREPEND if prepend else TextMode.APPEND
+            return _summary(bear.add_text(note, text, mode=mode))
+
+    @server.tool
+    def rename_note(note_id: str, new_title: str) -> dict:
+        """Change a note's title, keeping the body."""
+        with Bear(db_path) as bear:
+            return _summary(bear.rename(_require(bear, note_id), new_title))
+
+    @server.tool
+    def add_tag(note_id: str, tag: str) -> dict:
+        """Add a tag to a note (no leading #)."""
+        with Bear(db_path) as bear:
+            return _summary(bear.add_tag(_require(bear, note_id), tag))
+
+    @server.tool
+    def remove_tag(note_id: str, tag: str) -> dict:
+        """Remove a tag from a note."""
+        with Bear(db_path) as bear:
+            return _summary(bear.remove_tag(_require(bear, note_id), tag))
+
+    @server.tool
+    def trash_note(note_id: str) -> dict:
+        """Move a note to Bear's trash. One-way: restoring requires Bear's UI."""
+        with Bear(db_path) as bear:
+            return _summary(bear.trash(_require(bear, note_id)))
+
+    @server.tool
+    def archive_note(note_id: str) -> dict:
+        """Archive a note. One-way: unarchiving requires Bear's UI."""
+        with Bear(db_path) as bear:
+            return _summary(bear.archive(_require(bear, note_id)))
+
+    @server.tool
+    def open_note_in_bear(note_id: str) -> str:
+        """Bring a note up in the Bear app on the user's screen."""
+        with Bear(db_path) as bear:
+            note = _require(bear, note_id)
+            bear.open(note)
+            return f"Opened {note.title!r} in Bear"
+
+    return server
+
+
+def run(db_path: Path = DEFAULT_DB_PATH) -> None:
+    """Serve over stdio (the only supported transport)."""
+    build_server(db_path).run(transport="stdio", show_banner=False)
+
+
+__all__ = ["build_server", "run"]

bearcli-1.7.0/src/bearcli/skills/bear-notes/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: bear-notes
+description: Read, search, create, and manage the user's Bear notes with the bearcli CLI. Use when the user asks anything about their Bear notes — finding, reading, or summarizing notes, creating or editing notes, tags, archiving/trashing, or exporting their library.
+---
+
+# Working with Bear notes via bearcli
+
+bearcli reads notes directly and performs writes through the Bear app,
+verifying each change. Requires macOS with Bear installed. If `bearcli` is
+not on PATH (command not found), install it — ask the user first:
+`brew install michel-tricot/tap/bearcli` (or `uv tool install bearcli`, or
+`pipx install bearcli`).
+
+## Reading and searching
+
+Always use machine-readable output instead of parsing tables:
+
+- `bearcli note list -f json` — notes as JSON (id, title, tags, dates, status
+  booleans). `-f text` is TSV: id, modified, tags, status, title.
+- `bearcli note list --ids` — bare ids, one per line.
+- Filters compose: `--tag work` (includes nested `work/ideas`), `-n 50` /
+  `--all`, `--modified-after 2026-07-01`, `--only pinned|encrypted|trashed|archived`,
+  `--trashed` / `--archived` to include those notes.
+- `bearcli search "query" -f json` — case-insensitive substring over titles,
+  tags, and content, with a `snippet` per hit. Add `--fuzzy` for typo-tolerant
+  ranked matching (adds a `score`).
+- `bearcli get <id>` — full markdown content. `-f json` adds metadata and
+  attachment paths; `-r` rewrites attachment references to absolute file paths.
+- Note ids accept unique prefixes of 4+ chars (`bearcli get c44d09dc`); an
+  ambiguous prefix errors and lists the candidates.
+- `bearcli tag list -f text` — all tags with note counts (count<TAB>tag).
+- `bearcli stats -f json` — library totals: note/tag/attachment counts, words,
+  notes per year, top tags.
+
+## Writing (launches the Bear app if needed)
+
+Every write is verified and reports success or failure — trust the exit
+code.
+
+- `bearcli create "Title" --text "..." --tag work` — prints the new note's id.
+  Body can also be piped on stdin.
+- `bearcli note append <id> --text "..."` (`--prepend` for the top; stdin works).
+- `bearcli note rename <id> "New title"`.
+- `bearcli note replace <id>` — replaces the body from `--text`/stdin,
+  keeping the title. **Destructive**: confirm with the user before replacing
+  content you did not just read.
+- `bearcli note attach <id> file.png` — files up to 500 KB.
+- `bearcli note tag <id> name` / `bearcli note untag <id> name`.
+- `bearcli note trash <id>` / `bearcli note archive <id>` — reversible only
+  in Bear's UI; there is no untrash/unarchive command.
+- `bearcli tag rename old new` / `bearcli tag delete name` — affect ALL notes;
+  `tag delete` prompts (use `-y` only when the user asked for the deletion).
+- `bearcli open <id>` — brings the note up in the Bear app.
+
+## Secrets — important
+
+Note content can contain credentials. When sending note content anywhere
+outside the user's machine (messages, issues, commits, emails), fetch it with
+`bearcli get <id> --redact-secrets` so detected secrets become
+`[redacted: <rule>]` placeholders. Detection is best-effort; still eyeball
+the content.
+
+`bearcli export` scans all notes first and **blocks** if potential secrets
+are found. Prefer re-running with `--redact-secrets`; only use
+`--allow-secrets` if the user explicitly says to export secrets as-is.
+
+## Export
+
+- `bearcli export DIR` — every note becomes `DIR/<slug>-<shortid>/README.md`
+  plus an `attachments/` folder; the root `README.md`/`index.json` are a
+  generated catalog. `--sync` rewrites only changed notes and removes deleted
+  ones (never touches files it doesn't own).
+- `bearcli export DIR --sync --redact-secrets --push` — mirror to a git clone
+  (commit + push, self-converging). The repo should be private and dedicated.
+
+## Limits
+
+- Encrypted notes are listed but their content cannot be read.
+- All commands accept `--db PATH` (env `BEAR_DB_PATH`) to use a database copy.
+- `bearcli ui` is a full-screen interactive app for humans — never launch it
+  from an agent; use the commands above instead.
+- `bearcli --version` prints the installed version if you need to check it.
+- `bearcli mcp run` is an MCP server (stdio) for AI apps like Claude
+  Desktop; `bearcli mcp install <client>` configures a client to use it.
+  Neither is something to launch from a shell task.
+- This skill ships with the CLI: `bearcli skills install` refreshes the copy
+  in `~/.claude/skills/` after an upgrade; `bearcli skills list` and
+  `bearcli skills show bear-notes` inspect it. If commands here disagree
+  with the installed CLI, trust `--help`.