Getting Started

Getting Started

Get productive with bkmr in 5 minutes.

Installation

No dependencies required for basic functionality. Semantic search works offline — no API keys needed.

# Via Cargo (Rust)
cargo install bkmr

# Via pip/pipx
pip install bkmr

# Via Homebrew
brew install bkmr
export ORT_DYLIB_PATH=/opt/homebrew/lib/libonnxruntime.dylib

# From source
git clone https://github.com/sysid/bkmr.git && cd bkmr && cargo build --release

Linux Clipboard Dependencies

On Linux, bkmr needs an external clipboard tool (clipboard data is process-owned and would be lost when bkmr exits):

Display Server	Required Package	Install Command
Wayland	wl-clipboard	sudo apt install wl-clipboard
X11	xclip or xsel	sudo apt install xclip

bkmr auto-detects Wayland vs X11 via WAYLAND_DISPLAY.

Initial Setup

# 1. Generate configuration
bkmr --generate-config > ~/.config/bkmr/config.toml

# 2. Create database
bkmr create-db ~/.config/bkmr/bkmr.db

# 3. Set environment variable (add to .bashrc/.zshrc for persistence)
export BKMR_DB_URL=~/.config/bkmr/bkmr.db

Verify: bkmr --version and bkmr --help

Your First Bookmark

# Add a web URL (metadata is fetched automatically)
bkmr add https://github.com/sysid/bkmr rust,cli

# Search for it
bkmr search rust

# Open it in your browser
bkmr open <id>

Essential Workflows

Store a Code Snippet

# Add a snippet (copied to clipboard when accessed)
bkmr add "SELECT * FROM users WHERE active = true" sql,_snip_ --title "Active Users Query"

# Find and copy it
bkmr search --fzf -t _snip_
# Press Enter to copy to clipboard

Create a Shell Script Bookmark

# Add a shell script (interactive editor opens)
bkmr add "" ops,_shell_ --title "Deploy to Staging"
# Write your script in the editor, save, and it's stored

# Execute it later
bkmr search --fzf -t _shell_
# Press Enter, edit if needed, then execute

Save Markdown Documentation

# Add markdown that renders in browser with TOC
bkmr add "# Project Setup\n\n## Prerequisites\n- Node.js 18+\n- PostgreSQL" docs,_md_ --title "Setup Guide"

# Render it
bkmr open <id>

Interactive Fuzzy Search

bkmr search --fzf

# Keyboard shortcuts in fzf:
# Enter:  Open/execute bookmark
# Ctrl-O: Copy URL/content to clipboard
# Ctrl-E: Edit bookmark
# Ctrl-D: Delete bookmark
# Ctrl-A: Clone bookmark
# Ctrl-P: Show details

Upgrading

bkmr handles upgrades automatically:

1. Checks if database migrations are needed
2. Creates a timestamped backup (e.g., bkmr_backup_20250406.db)
3. Applies necessary migrations

cargo install bkmr --force   # or: pip install --upgrade bkmr / brew upgrade bkmr

For AI Agents

If you are integrating bkmr with an AI agent, see Agent Integration for JSON output, memory patterns, and bulk import.

Next Steps

• Core Concepts — Understand bookmarks, tags, and content types
• Basic Usage — Learn common commands and workflows
• Content Types — All content types and their actions
• Search and Discovery — Master search, tags, and filters
• Configuration — Customize bkmr to your workflow