bearcli 1.2.1__tar.gz → 1.4.0__tar.gz

{bearcli-1.2.1 → bearcli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bearcli
-Version: 1.2.1
+Version: 1.4.0
 Summary: The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal
 Keywords: bear,notes,cli,markdown,macos
 Author: Michel Tricot
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
 Requires-Dist: detect-secrets>=1.5.0
 Requires-Dist: rapidfuzz>=3.14.5
+Requires-Dist: textual>=8.2.8
 Requires-Dist: typer>=0.27.0
 Requires-Python: >=3.13
 Project-URL: Documentation, https://github.com/michel-tricot/bearcli/blob/main/docs/IMPLEMENTATION.md
@@ -23,9 +24,9 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-# 🐻 bearcli
+# 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** — read, search, export, and
+**The missing 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)
@@ -57,6 +58,7 @@ 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
@@ -79,8 +81,19 @@ 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, preview and inline markdown editor on the right.
+`/` search - `Enter` edit - `n`/`c` new note - `t`/`T` tag/untag (with
+autocompletion) - `o` open in Bear - `a` archive - `d` trash - `r` reload.
+Notes with detected secrets are marked 🚨; encrypted notes show 🔒 and keep
+their content in Bear.
+
 ### Search
 
 ```sh
@@ -90,7 +103,7 @@ bearcli search "quarterly planing" --fuzzy   # typo-tolerant, ranked by score
 
 ### Write
 
-Writes go through Bear's x-callback-url API — the database itself is never
+Writes go through Bear's x-callback-url API - the database itself is never
 written. These launch the Bear app if needed.
 
 ```sh
@@ -115,19 +128,19 @@ 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
+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).
+with a `[redacted: <rule>]` placeholder - notes in Bear are untouched).
 
-> **⚠️ Warning** — detection and redaction are best-effort: a secret that
+> **⚠️ 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
+> 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.
 
@@ -136,7 +149,7 @@ 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
+# 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
@@ -158,6 +171,16 @@ 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](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):
+
+```sh
+cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+```
+
 ## Development
 
 ```sh

{bearcli-1.2.1 → bearcli-1.4.0}/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-# 🐻 bearcli
+# 🐻 `bearcli`
 
-**The missing CLI for [Bear](https://bear.app) notes** — read, search, export, and
+**The missing 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)
@@ -34,6 +34,7 @@ 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
@@ -56,8 +57,19 @@ 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, preview and inline markdown editor on the right.
+`/` search - `Enter` edit - `n`/`c` new note - `t`/`T` tag/untag (with
+autocompletion) - `o` open in Bear - `a` archive - `d` trash - `r` reload.
+Notes with detected secrets are marked 🚨; encrypted notes show 🔒 and keep
+their content in Bear.
+
 ### Search
 
 ```sh
@@ -67,7 +79,7 @@ bearcli search "quarterly planing" --fuzzy   # typo-tolerant, ranked by score
 
 ### Write
 
-Writes go through Bear's x-callback-url API — the database itself is never
+Writes go through Bear's x-callback-url API - the database itself is never
 written. These launch the Bear app if needed.
 
 ```sh
@@ -92,19 +104,19 @@ 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
+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).
+with a `[redacted: <rule>]` placeholder - notes in Bear are untouched).
 
-> **⚠️ Warning** — detection and redaction are best-effort: a secret that
+> **⚠️ 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
+> 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.
 
@@ -113,7 +125,7 @@ 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
+# 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
@@ -135,6 +147,16 @@ 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](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):
+
+```sh
+cp -r skills/bear-notes ~/.claude/skills/   # or a project's .claude/skills/
+```
+
 ## Development
 
 ```sh

{bearcli-1.2.1 → bearcli-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bearcli"
-version = "1.2.1"
+version = "1.4.0"
 description = "The missing CLI for Bear notes — read, search, export, and manage your notes from the terminal"
 readme = "README.md"
 keywords = ["bear", "notes", "cli", "markdown", "macos"]
@@ -20,6 +20,7 @@ requires-python = ">=3.13"
 dependencies = [
     "detect-secrets>=1.5.0",
     "rapidfuzz>=3.14.5",
+    "textual>=8.2.8",
     "typer>=0.27.0",
 ]
 
@@ -37,6 +38,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "pytest>=9.1.1",
     "ruff>=0.16.0",
     "ty>=0.0.64",
 ]

bearcli-1.4.0/src/bearcli/cli/__init__.py

@@ -0,0 +1,25 @@
+"""Typer CLI for reading notes from the Bear note app."""
+
+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
+
+
+def _alias(name: str, target: str, func: Callable) -> None:
+    summary = (func.__doc__ or "").strip().splitlines()[0]
+    app.command(name, help=f"{summary} (alias for `bearcli {target}`)", rich_help_panel="Shortcuts")(func)
+
+
+_alias("list", "note list", list_notes)
+
+_alias("search", "note search", search)
+
+_alias("get", "note get", get)
+
+_alias("open", "note open", open_note)
+
+_alias("create", "note create", create)
+
+__all__ = ["app"]

bearcli-1.4.0/src/bearcli/cli/common.py

@@ -0,0 +1,112 @@
+"""Shared Typer apps, output types, and helpers for the CLI commands."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from bearcli import actions
+from bearcli.db import AmbiguousNoteId, BearDB, Note, note_metadata
+
+app = typer.Typer(help="Read notes from the Bear note app.", no_args_is_help=True, add_completion=False)
+
+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")
+
+app.add_typer(tag_app, name="tag")
+
+console = Console()
+
+
+class OutputFormat(StrEnum):
+    table = "table"
+    json = "json"
+    text = "text"
+
+
+class OnlyFilter(StrEnum):
+    pinned = "pinned"
+    encrypted = "encrypted"
+    trashed = "trashed"
+    archived = "archived"
+
+
+def _note_to_dict(note: Note, with_text: bool = False) -> dict:
+    data = note_metadata(note)
+    if with_text:
+        data["text"] = note.text
+        data["attachments"] = [
+            {
+                "filename": a.filename,
+                "path": str(a.path),
+                "size": a.size,
+                "exists": a.exists,
+            }
+            for a in note.attachments
+        ]
+    return data
+
+
+DbPathOption = Annotated[
+    Path,
+    typer.Option("--db", envvar="BEAR_DB_PATH", help="Path to the Bear SQLite database."),
+]
+
+
+def _open_db(path: Path) -> BearDB:
+    try:
+        return BearDB(path)
+    except FileNotFoundError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from None
+
+
+def _parse_date(value: str | None, option: str) -> datetime | None:
+    if value is None:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        console.print(
+            f"[red]Error:[/red] invalid date for {option}: {value!r} "
+            "(expected ISO format, e.g. 2026-07-01 or 2026-07-01T14:30)"
+        )
+        raise typer.Exit(2) from None
+
+
+def _text_or_stdin(text: str | None) -> str | None:
+    if text is None and not sys.stdin.isatty():
+        return sys.stdin.read()
+    return text
+
+
+def _require_note(db: BearDB, note_id: str) -> Note:
+    try:
+        note = db.get_note(note_id)
+    except AmbiguousNoteId as exc:
+        console.print(f"[red]Error:[/red] note id prefix {exc.prefix!r} matches several notes:")
+        for full_id, title in exc.matches:
+            console.print(f"  {full_id}  {title}")
+        raise typer.Exit(1) from None
+    if note is None:
+        console.print(f"[red]Error:[/red] no note with id {note_id!r}")
+        raise typer.Exit(1)
+    return note
+
+
+def _verify(ok: Callable[[], bool], success: str, failure: str) -> None:
+    if actions.wait_for(ok):
+        console.print(success)
+    else:
+        console.print(f"[red]Error:[/red] {failure}")
+        raise typer.Exit(1)

bearcli-1.4.0/src/bearcli/cli/export.py

@@ -0,0 +1,118 @@
+"""The export command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.markup import escape as rich_escape
+from rich.table import Table
+
+from bearcli.cli.common import (
+    DbPathOption,
+    _open_db,
+    app,
+    console,
+)
+from bearcli.db import DEFAULT_DB_PATH
+from bearcli.export import export_notes
+from bearcli.gitsync import GitError, export_and_push
+from bearcli.secrets import SecretFinding, redaction_map, scan_notes
+
+
+def _report_secrets(findings: list[SecretFinding]) -> None:
+    table = Table(box=box.ROUNDED, header_style="bold")
+    table.add_column("Note", overflow="ellipsis", max_width=30)
+    table.add_column("ID", style="dim", no_wrap=True)
+    table.add_column("Rule", style="yellow")
+    table.add_column("Line", justify="right")
+    table.add_column("Match", style="red")
+    for f in findings:
+        table.add_row(f.note_title, f.note_id, f.rule, str(f.line), f.excerpt)
+    console.print(table)
+    notes = len({f.note_id for f in findings})
+    console.print(
+        f"[red]Export blocked:[/red] {len(findings)} potential secret(s) in {notes} note(s). "
+        "Move them somewhere safe (or into an encrypted note), re-run with --redact-secrets "
+        "to export with placeholders, or with --allow-secrets to export as-is."
+    )
+
+
+@app.command()
+def export(
+    dest: Annotated[Path, typer.Argument(help="Destination directory for the markdown files.")],
+    sync: Annotated[
+        bool,
+        typer.Option(
+            "--sync",
+            help="Only rewrite notes that changed since the last export instead of everything.",
+        ),
+    ] = False,
+    push: Annotated[
+        bool,
+        typer.Option(
+            "--push",
+            help="Treat DEST as a git clone: commit the export and push. Bear is the source of "
+            "truth — remote or manual edits are kept in history but overwritten in HEAD.",
+        ),
+    ] = False,
+    allow_secrets: Annotated[
+        bool,
+        typer.Option("--allow-secrets", help="Export even if the secret scan finds potential credentials."),
+    ] = False,
+    redact_secrets: Annotated[
+        bool,
+        typer.Option(
+            "--redact-secrets",
+            help="Export with detected secrets replaced by a [redacted: <rule>] placeholder "
+            "(notes in Bear are untouched).",
+        ),
+    ] = False,
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Export all notes as markdown files with frontmatter and attachments."""
+    if allow_secrets and redact_secrets:
+        console.print("[red]Error:[/red] --allow-secrets and --redact-secrets are mutually exclusive")
+        raise typer.Exit(2)
+    db = _open_db(db_path)
+    try:
+        redactions: dict[str, dict[str, str]] | None = None
+        if not allow_secrets:
+            with console.status("Scanning notes for secrets…", spinner="dots"):
+                candidates = db.list_notes(limit=None, include_archived=True, with_text=True)
+                findings = scan_notes(candidates)
+            if findings and not redact_secrets:
+                _report_secrets(findings)
+                raise typer.Exit(1)
+            if findings:
+                redactions = redaction_map(findings)
+        with console.status("Exporting…", spinner="dots") as status:
+            update = lambda msg: status.update(rich_escape(msg))  # noqa: E731
+            if push:
+                try:
+                    result, outcome = export_and_push(db, dest, sync=sync, progress=update, redactions=redactions)
+                except GitError as exc:
+                    console.print(f"[red]Error:[/red] {exc}")
+                    raise typer.Exit(1) from None
+            else:
+                result = export_notes(db, dest, sync=sync, progress=update, redactions=redactions)
+    finally:
+        db.close()
+
+    parts = [f"{result.written} written"]
+    if push:
+        parts.append(outcome)
+    if sync:
+        parts.append(f"{result.unchanged} unchanged")
+    if result.removed:
+        parts.append(f"{result.removed} removed")
+    if result.skipped_encrypted:
+        parts.append(f"{result.skipped_encrypted} encrypted skipped")
+    if result.index_updated:
+        parts.append("index updated")
+    if redactions:
+        secrets_count = sum(len(v) for v in redactions.values())
+        parts.append(f"{secrets_count} secret(s) redacted in {len(redactions)} note(s)")
+    console.print(f"Exported to {dest}: " + ", ".join(parts))

bearcli-1.4.0/src/bearcli/cli/misc.py

@@ -0,0 +1,109 @@
+"""Library-wide commands: stats and the terminal UI."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.table import Table
+
+from bearcli.cli.common import (
+    DbPathOption,
+    OutputFormat,
+    _open_db,
+    app,
+    console,
+)
+from bearcli.db import DEFAULT_DB_PATH
+
+
+@app.command()
+def stats(
+    fmt: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format: table or json."),
+    ] = OutputFormat.table,
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Show statistics about the note library."""
+    db = _open_db(db_path)
+    try:
+        notes = db.list_notes(limit=None, include_trashed=True, include_archived=True, with_text=True)
+        tag_counts = db.list_tags()
+        attachment_count, attachment_bytes = db.attachment_stats()
+    finally:
+        db.close()
+
+    active = [n for n in notes if not n.trashed and not n.archived]
+    by_year: dict[str, int] = {}
+    for n in notes:
+        if not n.trashed and n.created:
+            year = str(n.created.year)
+            by_year[year] = by_year.get(year, 0) + 1
+
+    data = {
+        "notes": len(notes),
+        "active": len(active),
+        "archived": sum(1 for n in notes if n.archived and not n.trashed),
+        "trashed": sum(1 for n in notes if n.trashed),
+        "pinned": sum(1 for n in notes if n.pinned and not n.trashed),
+        "encrypted": sum(1 for n in notes if n.encrypted and not n.trashed),
+        "words": sum(len((n.text or "").split()) for n in notes if not n.trashed),
+        "tags": len(tag_counts),
+        "attachments": attachment_count,
+        "attachment_bytes": attachment_bytes,
+        "notes_by_year": dict(sorted(by_year.items())),
+        "top_tags": [{"tag": t, "notes": c} for t, c in sorted(tag_counts, key=lambda tc: -tc[1])[:10]],
+    }
+
+    if fmt is OutputFormat.json:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    table = Table(box=box.ROUNDED, show_header=False, width=44)
+    table.add_column(style="bold")
+    table.add_column(justify="right")
+    table.add_row("Notes", str(data["notes"]))
+    table.add_row("  active", str(data["active"]))
+    table.add_row("  archived", str(data["archived"]))
+    table.add_row("  trashed", str(data["trashed"]))
+    table.add_row("  pinned", str(data["pinned"]))
+    table.add_row("  encrypted", str(data["encrypted"]))
+    table.add_row("Words", f"{data['words']:,}")
+    table.add_row("Tags", str(data["tags"]))
+    table.add_row("Attachments", f"{attachment_count} ({attachment_bytes / 1_000_000:.1f} MB)")
+    console.print(table)
+
+    if data["top_tags"]:
+        tag_table = Table(box=box.ROUNDED, header_style="bold", width=44)
+        tag_table.add_column("Top tags", style="cyan")
+        tag_table.add_column("Notes", justify="right")
+        for entry in data["top_tags"]:
+            tag_table.add_row(str(entry["tag"]), str(entry["notes"]))
+        console.print(tag_table)
+
+    year_table = Table(box=box.ROUNDED, header_style="bold", width=44)
+    year_table.add_column("Created", style="cyan")
+    year_table.add_column("Notes", justify="right")
+    for year, count in data["notes_by_year"].items():
+        year_table.add_row(year, str(count))
+    console.print(year_table)
+
+
+@app.command()
+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,
+    db_path: DbPathOption = DEFAULT_DB_PATH,
+) -> None:
+    """Bear in the terminal: search, edit, create, tag, and organize notes."""
+    from bearcli.tui import run_ui
+
+    db = _open_db(db_path)
+    try:
+        notes = db.list_notes(limit=None, tag=tag_filter, with_text=True)
+    finally:
+        db.close()
+    run_ui(notes, fuzzy=fuzzy, db_path=db_path, tag_filter=tag_filter)