bkmr

Combine any snippet (code, urls, markdown, text) with powerful search, interpolation and execution.

Beyond Bookmarks and Snippets: A CLI Knowledge Management System

bkmr reborn

bkmr - selected crate of the week 482 - is a fast, feature-rich command-line tool that extends bookmark management, snippet handling, markdown rendering, script execution and more.

Organize, find, and apply your various content types:

• Web URLs with automatic metadata extraction
• Code snippets for quick access and reuse
• Shell commands with execution capabilities
• Markdown documents with live rendering
• Plain text with template interpolation
• Local files and directories
• Semantic embeddings for AI-powered search

Why bkmr?

• Developer-focused: Integrates seamlessly with your workflow and toolchain
• Multifunctional: Handles many content types with context-aware actions
• Intelligent: Full-text and semantic search capabilities
• Privacy-focused: Local database, no cloud dependencies unless enabled
• Fast: 20x faster than similar Python tools

NEW: Editor Integrations!

• Built-in LSP server: Use bkmr lsp for VS Code, Vim, Emacs - automatic snippet completion with language-aware filtering
• Neovim Plugin: Visual interface with Telescope integration and zero configuration
• IntelliJ Plugin: JetBrains Marketplace plugin for all IDEs

Core Features

# Quick fuzzy search across your content with interactive selection
bkmr search --fzf

# Advanced filtering with tags
bkmr search -t python,security "authentication"

# Add web URLs, enrich with metadata automatically
bkmr add https://example.com tag1,tag2  # title, description, etc will be loaded automatically

# Store code snippets
bkmr add "SELECT * FROM users WHERE role = 'admin'" sql,snippet --type snip --title "My Sql"
bkmr search --fzf --fzf-style enhanced -t _snip_  # show interactive selection menu

# shell scripts, added via interactive editor
bkmr add sysadmin,utils --type shell
# Bookmark Template
# Lines starting with '#' are comments and will be ignored.
# Section markers (---SECTION_NAME---) are required and must not be removed.

---ID---

---URL---
#!/bin/bash
echo "Hello World!"
---TITLE---
System Status
---TAGS---
_shell_
---COMMENTS---
Show the system status
---EMBEDDABLE---
false
---END---

# Run the script (default action for this content-type is called automatically when search returns exactly one)
bkmr search -t _shell_ "System Status"
> Found 1 bookmark: System Status (ID: 22). Executing default action...
> Execute: #!/bin/bash
echo "Hello World!"
# Edit the command if needed, press Enter to execute, or Ctrl-C to cancel
> Hello World!


# Store markdown which will be rendered in the browser with Table of Contents
bkmr add "# Project Notes\n\n## Tasks\n- [ ] Complete documentation\n- [ ] Write tests" notes,project --type md --title Markdown
bkmr open <id>  # opens in browser with interactive TOC sidebar for navigation
bkmr add "/path/to/markdown.md" --type md -t "Markdown File to be rendered"  # automatically detects path instead of content

# View markdown files directly without storing as bookmarks
bkmr open --file README.md              # renders with TOC, syntax highlighting
bkmr open --file ~/docs/notes.md        # supports relative and absolute paths
bkmr open --file ./documentation.md     # automatic markdown rendering in browser

# Store environment variables for sourcing in a shell
bkmr add "export DB_USER=dev\nexport DB_PASSWORD=secret\nexport API_KEY=test_key" dev,env --type env --title 'My Environment'
bkmr search --fzf --fzf-style enhanced -t _env_  # select it for sourcing

# Import files with frontmatter parsing and base path support
bkmr import-files ~/scripts/backup.sh --base-path SCRIPTS_HOME
bkmr edit 123  # Smart editing: opens source file for file-imported bookmarks

# Execute shell commands via bookmark (deprecated, use content-type _shell_ instead)
bkmr add "shell::find ~/projects -name '*.go' | xargs grep 'func main'" tools,search --title 'Search Golang'

# Semantic search with AI
bkmr --openai sem-search "containerized application security" --limit 3

Bookmarks

Snippets

Demos

See bkmr in action:

• Overview

• Getting Started

• Search and Filter

• Edit and Update

• Tag Management

Getting Started

1. Install:

   cargo install bkmr
   
   # or via pip/pipx/uv
   pip install bkmr
   
   # or via brew
   brew install bkmr
   
   

2. Setup:

   # Configuration 
   bkmr --generate-config > ~/.config/bkmr/config.toml
   
   # Create database
   bkmr create-db ~/.config/bkmr/bkmr.db
   
   # Optional: Configure location (override config.toml)
   export BKMR_DB_URL=~/path/to/db
   

Platform Compatibility

Wayland Support: bkmr includes native Wayland clipboard support for modern Linux desktops.

• Supported compositors: Hyprland, Sway, and other compositors supporting wlr-data-control-unstable-v1 protocol
• Automatic detection: Falls back to X11/XWayland if Wayland protocols are unavailable
• Compatibility: Check your compositor support at wayland.app

3. Start using:

   # Add your first bookmark
   bkmr add https://github.com/yourusername/yourrepo github,project
   
   # Find it again
   bkmr search github
   

Command Reference

Command	Description
search	Search across all content with full-text and tag filtering
sem-search	AI-powered semantic search using OpenAI embeddings
add	Add new content (URLs, snippets, files, shell commands, etc.)
open	Launch or interact with stored items (supports script arguments)
edit	Smart editing: auto-detects file-imported bookmarks for source file editing
import-files	Import files/directories with frontmatter parsing and base path support
create-shell-stubs	Generate shell function stubs for all shell script bookmarks
tags	View and manage your tag taxonomy
set-embeddable	Configure items for semantic search

Smart Content Actions

bkmr intelligently handles different content types with appropriate actions:

Content Type	Default Action	System Tag
URLs	Open in browser	(none)
Snippets	Copy to clipboard	_snip_
Shell Scripts	Interactive edit then execute in terminal	_shell_
Environment Variables	Print to stdout for sourcing in shell	_env_
Markdown	Render in browser with TOC sidebar	_md_
Text Documents	Copy to clipboard	_imported_
Local Files	Open with default application	(none)

Advanced Features

• Smart editing system: Automatically detects file-imported bookmarks and edits source files directly
• File import with base paths: Import files with portable path storage using configurable base path variables
• Interactive shell editing: Shell scripts present an interactive editor with vim/emacs bindings before execution
• Template interpolation: Use Jinja-style templates in URLs and commands
• Content embedding: Store semantic representations for AI-powered search
• Context-aware actions: Different behaviors based on content type
• Multiple output formats: Terminal display, clipboard, or JSON export

Shell Script Interaction

Shell scripts (_shell_ content type) provide an interactive editing experience:

• Pre-filled editing: Original script appears ready for modification
• Vim/Emacs bindings: Automatically detects your shell's edit mode from .inputrc, $ZSH_VI_MODE, etc.
• Parameter support: Add arguments, modify commands, or combine multiple commands
• History integration: Commands are saved to ~/.config/bkmr/shell_history.txt
• Configurable behavior: Can be disabled via configuration for direct execution

# Interactive mode (default) - edit before execution
bkmr search -t _shell_ "backup script"
Execute: rsync -av /home/user/docs /backup/
# Edit to add parameters: rsync -av /home/user/docs /backup/$(date +%Y%m%d)/
# Press Enter to execute

# Direct execution with arguments (skip interactive editing)
bkmr open --no-edit <id> -- arg1 arg2 arg3

# Disable interactive mode via configuration
export BKMR_SHELL_INTERACTIVE=false
# or in ~/.config/bkmr/config.toml:
# [shell_opts]
# interactive = false

Shell Function Stubs

Create shell functions for all your shell script bookmarks to enable direct execution with arguments:

# Generate shell function stubs
bkmr create-shell-stubs

# Example output:
# backup-database() { bkmr open --no-edit 123 -- "$@"; }
# export -f backup-database
# deploy-app() { bkmr open --no-edit 124 -- "$@"; }
# export -f deploy-app

# Source directly into your current shell
source <(bkmr create-shell-stubs)

# Add to your shell profile for permanent access
echo 'source <(bkmr create-shell-stubs)' >> ~/.bashrc
# or for better performance, cache the output:
bkmr create-shell-stubs >> ~/.bashrc

# Now use your bookmarked scripts directly with arguments
backup-database production --incremental
deploy-app staging --rollback

Function Name Generation:

• Preserves hyphens: "backup-database" → backup-database()
• Converts spaces to underscores: "Deploy Script" → deploy_script()
• Handles edge cases: "2fa-setup" → script-2fa-setup()

File Import and Smart Editing

bkmr supports importing files with structured metadata and provides intelligent editing capabilities:

# Import files with frontmatter parsing
bkmr import-files ~/scripts/backup.sh ~/docs/notes.md

# Import with base path configuration for portable storage
bkmr import-files scripts/backup.sh --base-path SCRIPTS_HOME

# Smart editing automatically detects file-imported bookmarks
bkmr edit 123  # Opens source file in $EDITOR if file-imported, database editor otherwise

# Force database content editing
bkmr edit 123 --force-db

File Import Features:

• Frontmatter parsing: Supports YAML (--- delimited) and hash-style (# key: value) metadata
• Base path configuration: Store portable paths using configurable base path variables
• Incremental updates: SHA-256 hash tracking for efficient re-imports
• Directory traversal: Recursive processing with .gitignore support

Smart Editing Features:

• Automatic detection: Identifies file-imported vs regular bookmarks
• Source file editing: Opens original files in your $EDITOR for file-imported bookmarks
• Metadata synchronization: Changes to frontmatter automatically sync to database
• Path resolution: Handles base path variables and environment expansion

Configuration Example:

# ~/.config/bkmr/config.toml
[base_paths]
SCRIPTS_HOME = "$HOME/scripts"
DOCS_HOME = "$HOME/documents"
WORK_SCRIPTS = "/work/automation/scripts"

For detailed documentation on advanced features:

• Configuration Options
• Content Types
• File Import and Smart Editing
• Advanced Usage
• Semantic Search

Editor Integrations

Instead of switching between editor and terminal, access snippets directly within the IDE.

Neovim Plugin (Recommended for Neovim Users)

bkmr-nvim provides the best Neovim integration experience with visual interface and zero configuration.

Installation with lazy.nvim:

{
  "sysid/bkmr-nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    require("bkmr").setup() -- Zero config required!
  end,
}

Key Features:

• Visual snippet browser: Telescope/FZF integration for browsing and searching
• In-editor editing: Create and edit snippets without leaving Neovim
• Automatic LSP setup: Configures bkmr LSP server automatically
• Custom commands: :Bkmr, :BkmrEdit, :BkmrSearch

Built-in LSP Server

bkmr includes a built-in Language Server Protocol (LSP) server accessible via bkmr lsp for any LSP-compatible editor (VS Code, Vim, Emacs, Sublime, etc.).

Usage:

# Start the LSP server (typically configured in your editor)
bkmr lsp

# Disable template interpolation if needed
bkmr lsp --no-interpolation

Key Features:

• Automatic completion: Snippets appear in completion popup while typing
• Language-aware filtering: Shows only relevant snippets based on file type
• Universal snippets: Write once in Rust syntax, automatically adapt to any language
• Template interpolation: Server-side processing of bkmr templates
• LSP commands: CRUD operations and utilities directly from editor

For comprehensive documentation including editor configuration, see LSP Documentation.

IntelliJ Platform Plugin

bkmr-intellij-plugin brings bkmr integration to all JetBrains IDEs.

Key Features:

• Seamless LSP integration: Automatic snippet completion with no manual triggers
• Tab navigation: Full snippet placeholder support with Tab/Shift+Tab navigation
• Cross-platform: Works in IntelliJ IDEA, PyCharm, WebStorm, CLion, RustRover, and all JetBrains IDEs
• Filepath comments: Insert relative filepaths as comments with smart language detection

Universal Snippets

Both integrations support universal snippets - write snippets once using natural Rust syntax, and they automatically translate to your target language:

// Universal snippet (stored as Rust syntax)
// Function: {{ function_name }}
// TODO: implement
    return {{ value }};

Automatic translation:

• Python: // comment → # comment
• HTML: // comment → <!-- comment -->
• Indentation: Adapts to language conventions (tabs for Go, 2 spaces for JS, etc.)

Developer Workflow Integration

bkmr transforms your terminal into a knowledge hub for development tasks:

1. Unified knowledge store - Access code snippets, documentation, and resources with one command
2. Reduced context switching - Launch applications and execute commands without leaving your workflow
3. Smart clipboard management - Quickly access common snippets without leaving the terminal
4. Documentation at your fingertips - Render markdown and technical notes instantly
5. Automation shortcuts - Turn complex command sequences into reusable bookmarks

Upgrading from Previous Versions

If you're upgrading from a previous version, bkmr will automatically:

1. Check for necessary database migrations
2. Create a timestamped backup of your current database
3. Apply migrations to support newer features

Development

Building from Source

# Clone the repository
git clone https://github.com/sysid/bkmr.git
cd bkmr

# Build debug version
cargo build

# Build release version
cargo build --release

Running Tests

IMPORTANT: All tests must be run single-threaded due to shared SQLite database state:

# Run tests (REQUIRED: single-threaded)
cargo test -- --test-threads=1

# Or use the Makefile (pre-configured for single-threaded execution)
make test

# Run with visible output
cargo test -- --test-threads=1 --nocapture

Why single-threaded?

• Tests share a common SQLite database and environment variables
• Parallel execution causes race conditions and intermittent failures
• Single-threaded execution ensures reliable, deterministic test results

Development Commands

# Format code
make format

# Run linter
make lint

# Clean build artifacts
make clean

# Install development version
make install

Community and Contributions

We welcome contributions! Please check our Contributing Guidelines to get started.

For developers: Remember to always run tests with --test-threads=1 to avoid database conflicts.