bkmr - selected crate of the week 482 - is a fast, feature-rich command-line tool that extends far beyond traditional bookmark management.
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
- 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
# 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:
8000
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
bkmr add "# Project Notes\n\n## Tasks\n- [ ] Complete documentation\n- [ ] Write tests" notes,project --type md --title Markdown
bkmr open <id> # open it in WEB browser
bkmr add "/path/to/markdown.md" --type md -t "Markdown File to be rendered" # automatically detects path instead of content
# 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 3See bkmr in action:
-
Install:
cargo install bkmr # or via pip/pipx/uv pip install bkmr # or via brew brew install bkmr
-
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
-
Start using:
# Add your first bookmark bkmr add https://github.com/yourusername/yourrepo github,project # Find it again bkmr search github
| 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 |
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 and view in browser | _md_ |
| Text Documents | Copy to clipboard | _imported_ |
| Local Files | Open with default application | (none) |
- 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 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 = falseCreate 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 --rollbackFunction Name Generation:
- Preserves hyphens:
"backup-database"→backup-database() - Converts spaces to underscores:
"Deploy Script"→deploy_script() - Handles edge cases:
"2fa-setup"→script-2fa-setup()
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-dbFile 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
.gitignoresupport
Smart Editing Features:
- Automatic detection: Identifies file-imported vs regular bookmarks
- Source file editing: Opens original files in your
$EDITORfor 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:
bkmr transforms your terminal into a knowledge hub for development tasks:
- Unified knowledge store - Access code snippets, documentation, and resources with one command
- Reduced context switching - Launch applications and execute commands without leaving your workflow
- Smart clipboard management - Quickly access common snippets without leaving the terminal
- Documentation at your fingertips - Render markdown and technical notes instantly
- Automation shortcuts - Turn complex command sequences into reusable bookmarks
If you're upgrading from a previous version, bkmr will automatically:
- Check for necessary database migrations
- Create a timestamped backup of your current database
- Apply migrations to support newer features
We welcome contributions! Please check our Contributing Guidelines to get started.