CLI: Human-readable output for `bm tool` commands (demo-ready formatting)

[bm-clawd]

Summary

The bm tool subcommands (search-notes, read-note, build-context, etc.) currently output raw JSON. This is great for programmatic use but makes CLI demos and marketing GIFs look rough — escaped unicode, \n literals, giant unbroken strings.

Meanwhile, bm project list, bm status, and bm doctor already have beautiful Rich-formatted output that's demo-ready. We should bring the same polish to the tool commands.

What Needs Work

bm tool search-notes

Current: Raw JSON with full note content in matched_chunk as escaped strings
Wanted: Formatted table or list showing:

• Note title + permalink
• Relevance score
• Short snippet of matched content (truncated, rendered — not escaped)
• File path

Something like:

 Search: 'what happened in the team meeting'  (3 results)

 1. BM Group Therapy - Mar 15, 2026            120%
    meetings/2026/BM Group Therapy - Mar 15, 2026.md
    Weekly team sync. Focus on marketing priorities, benchmark results...

 2. Emma Bates Interview                        105%
    people/emma-bates-interview.md
    Startup founder, Alexandria VA. Uses BM ~100x/day...

 3. conversations-2026-02-28                     77%
    memory/conversations-2026-02-28.md
    ...

bm tool read-note

Current: JSON with content as a single escaped string field
Wanted: Render the actual markdown content directly to terminal (like cat but with the frontmatter shown cleanly). Rich already supports markdown rendering.

bm tool build-context

Current: JSON
Wanted: Formatted view showing the target note + related notes with relation types

bm tool recent-activity

Current: JSON
Wanted: Timeline-style list with timestamps and note titles

Implementation Notes

• Keep JSON as default for programmatic use (piping, jq, scripts)
• Add --format text or --pretty flag for human-readable output
• Or detect TTY: if stdout is a terminal, use pretty format; if piped, use JSON
• Use Rich for formatting (already a dependency)
• Truncate long content in search results to ~200 chars

Why This Matters

We're using VHS by Charmbracelet to generate automated CLI demo GIFs for marketing. The project management commands (project list, status, doctor) look fantastic. But the core value prop commands (search, read) look like raw API dumps. The search demo is the most compelling story — 'natural language search across your knowledge graph' — but the current output undersells it.

Context

• VHS tape files ready at demos/ in workspace — can regenerate GIFs immediately once formatting ships
• bm project list and bm status are the gold standard for what good CLI output looks like
• This week's content priority includes OpenClaw plugin demos and benchmark results — polished CLI output would help both

VHS Demo Recording Setup

We use VHS by Charmbracelet to generate CLI demo GIFs automatically. Once the formatting is updated, regenerate demos to verify they look good.

Install VHS

brew install charmbracelet/tap/vhs

Tape File Format

Tape files are simple scripts that describe terminal recordings. Example:

# Basic Memory — Search Demo
Output demos/bm-search.gif

Set Shell "bash"
Set FontSize 14
Set Width 1400
Set Height 800
Set Theme "Catppuccin Mocha"
Set Padding 20
Set TypingSpeed 40ms

Type "bm tool search-notes 'what happened in the team meeting'"
Enter
Sleep 8s

Type "bm tool read-note 'BM Group Therapy - Mar 15, 2026' | head -40"
Enter
Sleep 8s

Run a Recording

vhs demos/bm-search.tape
# Outputs demos/bm-search.gif

Key VHS Commands

• Output <path>.gif — set output file (supports .gif, .webm, .mp4)
• Set Shell "bash" — shell to use
• Set Theme "Catppuccin Mocha" — terminal theme (many built-in)
• Set FontSize 14 / Set Width 1400 / Set Height 800 — dimensions
• Type "command" — types text with simulated keystrokes
• Enter — press enter
• Sleep 5s — wait for output to render
• Hide / Show — hide setup commands (PATH, clear, etc.)

Tips from Our Experience

• Sleep times matter: bm tool commands take 3-8s on first run (embedding model load). Use Sleep 8s or more after search commands.
• PATH: On machines with Homebrew BM 0.18.0, the correct binary may be at ~/.local/bin/bm (0.20.2). Use Hide section to set PATH before recording.
• TTY detection: If implementing auto-pretty (TTY=pretty, pipe=JSON), VHS runs in a PTY so it will get the pretty output automatically — which is what we want for demos.
• Verify frames: Extract frames with ffmpeg to check output before publishing:

  ffmpeg -i demos/output.gif -vf "select=eq(n\\,200)" -frames:v 1 -update 1 frame.png -y

Existing Tape Files

Check demos/ directory for existing tape files that can be updated and re-recorded once formatting ships.

What Good Output Looks Like

bm project list and bm status are the reference — Rich-formatted tables, colored headers, clean box drawing. Match that quality for the tool commands.

[claude]

Claude finished @bm-clawd's task in 1m 18s —— View job

---

Issue Triage

• Gather context — read existing CLI tool command structure
• Classify issue type, priority, component, complexity
• Apply labels
• Provide triage summary

---

Analysis

Type: Enhancement — improving existing bm tool commands with human-readable output. The bm status command is a clear precedent: it already has both --json flag (for machine use) and a beautiful Rich-formatted default view. The tool.py commands all hardcode output_format="json" and call _print_json() with no TTY detection or formatting option.

Priority: Medium — this is a UX/marketing improvement, not a bug. Functionality works correctly today; this improves demo quality and usability.

Component: CLI (src/basic_memory/cli/commands/tool.py)

Complexity: Medium — the pattern is well-established in status.py and project.py. Implementation requires:

1. Adding a --format / --pretty flag (or TTY detection) to multiple commands
2. Building Rich formatters for: search results, note content, context graph, recent activity timeline
3. No database/schema changes needed

No duplicates found.

---

Recommended Implementation Approach

The bm status command is the gold standard — it defaults to Rich output and falls back to JSON with --json. The bm tool commands should follow the same pattern:

1. search-notes → Rich table/list with title, score, snippet, path (truncated to ~200 chars)
2. read-note → Render markdown via rich.markdown.Markdown (Rich already supports this)
3. build-context → Panel showing primary note + related notes tree with relation types
4. recent-activity → Timeline list with timestamps and note titles

Strategy options:

• TTY detection (sys.stdout.isatty()) — pretty by default in terminal, JSON when piped. Zero new flags needed.
• --json flag — explicit opt-in to JSON (mirrors bm status pattern). Cleaner for users who want JSON interactively.

The bm status precedent (--json flag, Rich default) is probably the better match for consistency.

Label applied: enhancement