Skip to content

Basic Usage

Jump to bottom
sysid edited this page Oct 12, 2025 · 2 revisions

Basic Usage

This guide covers the most common bkmr operations for daily use. For advanced features, see Advanced Workflows.

Overview

bkmr is designed around a simple workflow:

  1. Add - Store URLs, snippets, scripts, and documents
  2. Search - Find content using keywords, tags, or fuzzy finder
  3. Open - Use content with appropriate action (open, copy, execute)
  4. Edit - Update existing bookmarks when needed

Adding Content

URLs

Basic URL Addition:

# Simple URL bookmark
bkmr add https://example.com

# With tags
bkmr add https://docs.python.org/3/ python,docs,reference

# With custom title
bkmr add https://api.example.com api,reference --title "API Documentation"

Automatic Metadata Extraction:

# bkmr automatically fetches title, description from web pages
bkmr add https://github.com/sysid/bkmr github,rust

# Output: Fetching metadata...
# Title: "bkmr - Fast bookmark and snippet manager"
# Description automatically extracted

Code Snippets

Interactive Creation:

# Open editor for snippet creation
bkmr add python,async,_snip_

# Editor opens with template:
---ID---

---URL---
# Enter your code here
---TITLE---
Async Example
---TAGS---
_snip_,python,async
---COMMENTS---
Async function example
---END---

Direct Addition:

# Add snippet directly
bkmr add 'SELECT * FROM users WHERE active = true' sql,_snip_ --title "Active Users Query"

# Add from stdin
echo 'console.log("Hello World")' | bkmr add --stdin javascript,_snip_ --title "Console Log"

# Multi-line snippet
bkmr add 'async fn fetch_data() {
    let response = reqwest::get("https://api.example.com").await?;
    Ok(response.json().await?)
}' rust,async,_snip_ --title "Rust Async Fetch"

Shell Scripts

Interactive Shell Script Creation:

# Open editor for shell script
bkmr add sysadmin,backup,_shell_

# Editor opens with template for script input
---URL---
#!/bin/bash
echo "Backup started at $(date)"
tar -czf backup-$(date +%Y%m%d).tar.gz /data/
---TITLE---
Daily Backup
---TAGS---
_shell_,backup,sysadmin
---END---

Direct Shell Script Addition:

# Add script directly
bkmr add '#!/bin/bash
kubectl get pods --all-namespaces' k8s,admin,_shell_ --title "List All Pods"

# Add with type flag
bkmr add "docker ps -a | grep myapp" docker,monitoring --type shell --title "Check App Containers"

Markdown Documents

Add Markdown Content:

# Short markdown content
bkmr add "# API Notes

## Endpoints
- GET /users
- POST /users

## Authentication
Use Bearer token" api,docs,_md_ --title "API Quick Reference"

# Add markdown file reference
bkmr add "/path/to/documentation.md" docs,project --type md --title "Project Documentation"

View Markdown Without Storing:

# Render markdown file directly without creating bookmark
bkmr open --file README.md              # Relative path
bkmr open --file ~/docs/notes.md        # Absolute path
bkmr open --file ./documentation.md     # Current directory

# Supports environment variables
bkmr open --file "$HOME/docs/api.md"

Environment Variables

Add Environment Configuration:

# Development environment
bkmr add "export DATABASE_URL=postgres://localhost:5432/dev
export API_KEY=dev_key_123
export DEBUG=true" dev,env,_env_ --title "Dev Environment"

# Production environment
bkmr add "export DATABASE_URL=postgres://prod-db:5432/prod
export API_KEY=prod_key_456
export DEBUG=false" prod,env,_env_ --title "Prod Environment"

Searching Content

Basic Search

Simple Text Search:

# Search all content
bkmr search "python"

# Search with multiple terms
bkmr search "docker compose"

# Phrase search
bkmr search "single-page application"

Output:

 1. ID: 42 | Python Async Guide | Tags: python, async, tutorial
    URL: https://realpython.com/async-io-python/
    Description: Complete guide to async programming in Python

 2. ID: 87 | Python Decorators | Tags: python, advanced, _snip_
    Snippet: def timer(func): ...

Tag-Based Search

Filter by Tags:

# All tags must match (AND)
bkmr search -t python,async "async"

# Any tag must match (OR)
bkmr search -T python,rust,go

# Exclude tags
bkmr search -n deprecated,old

# Combine filters
bkmr search -t python -n beginner "decorator"

System Tag Filtering

Find by Content Type:

# Find only code snippets
bkmr search -t _snip_ "docker"

# Find only shell scripts
bkmr search -t _shell_ "backup"

# Find only markdown documents
bkmr search -t _md_ "api"

# Find environment variable sets
bkmr search -t _env_ "production"

# Combine with other tags
bkmr search -t _snip_,python "async"

Fuzzy Finder Search

Interactive Search with FZF:

# Launch fuzzy finder
bkmr search --fzf

# Pre-filtered fuzzy search
bkmr search --fzf -t python

# Enhanced colored output
bkmr search --fzf --fzf-style enhanced

# Search snippets only
bkmr search --fzf -t _snip_

# Search shell scripts only
bkmr search --fzf -t _shell_

FZF Keyboard Shortcuts:

Key Action
Enter Execute default action (open/copy/run)
Ctrl-O Copy URL/content to clipboard
Ctrl-E Edit bookmark
Ctrl-D Delete bookmark
Ctrl-Y Copy to clipboard (alternative)
Esc Quit fuzzy finder

Advanced Search

Column-Specific Search:

# Search only in URLs
bkmr search "url:github"

# Search only in titles
bkmr search "metadata:docker"

# Search only in descriptions
bkmr search "desc:authentication"

# Search only in tags
bkmr search "tags:python"

# Combined column search
bkmr search "tags:docker desc:compose"

Sort and Limit:

# Most recent bookmarks
bkmr search --descending --limit 10

# Oldest bookmarks
bkmr search --ascending --limit 10

# Recent Python bookmarks
bkmr search -t python --descending --limit 5

JSON Output

For Scripting:

# JSON output
bkmr search --json "python" | jq '.[] | {title, url}'

# Get only IDs (no-print mode)
bkmr search -t python --np

# Example: Process IDs
for id in $(bkmr search -t needs-update --np); do
    echo "Processing bookmark $id"
    bkmr update -t updated "$id"
done

Using Content (Open Command)

URLs

Open in Browser:

# Open by ID
bkmr open 42

# Search and open (when exactly one result)
bkmr search "python async guide"
# Output: Found 1 bookmark. Opening...

# Fuzzy select and open
bkmr search --fzf "python"  # Select with Enter

Code Snippets

Copy to Clipboard:

# Open snippet by ID (copies to clipboard)
bkmr open 87

# Or use yank command explicitly
bkmr yank 87

# Search and copy
bkmr search --fzf -t _snip_,python  # Select and press Enter to copy

Verify Clipboard:

# After copying snippet
pbpaste    # macOS
xclip -o   # Linux with X11
wl-paste   # Linux with Wayland

Shell Scripts

Interactive Execution (Default):

# Opens interactive editor before execution
bkmr open 123

# Editor shows:
Execute: ./deploy.sh
# Edit command, add parameters
Execute: ./deploy.sh --env staging --dry-run
# Press Enter to execute, Ctrl-C to cancel

Direct Execution:

# Skip interactive editing
bkmr open --no-edit 123

# With arguments
bkmr open --no-edit 123 -- arg1 arg2 arg3

# Example: deployment with environment
bkmr open --no-edit 456 -- --env production --verbose

Using Shell Function Stubs:

# Generate and source function stubs
source <(bkmr search --shell-stubs)

# Now use bookmarked scripts directly
backup-database production --incremental
deploy-app staging --rollback
monitoring-setup --enable-alerts

Markdown Documents

Render in Browser:

# Open markdown by ID
bkmr open 91

# Features:
# - Interactive Table of Contents (sidebar)
# - Syntax highlighting for code blocks
# - Responsive design
# - Smooth scrolling between sections

Environment Variables

Source into Shell:

# Load environment variables
eval "$(bkmr open 67)"

# Or search and load
eval "$(bkmr search --fzf -t _env_,dev)"  # Select dev environment

# Verify variables loaded
echo $DATABASE_URL
echo $API_KEY

Editing Content

Basic Editing

Edit by ID:

# Open editor for bookmark
bkmr edit 42

# Editor shows all fields:
---ID---
42
---URL---
https://example.com
---TITLE---
Example Site
---TAGS---
example,reference
---COMMENTS---
Example website for testing
---END---

Smart Editing (File-Imported Bookmarks):

# For file-imported bookmarks, opens source file in $EDITOR
bkmr edit 123

# If source file exists: Opens ~/scripts/backup.sh in your editor
# If source file missing: Falls back to database content editor

# Force database editing even for file-imported bookmarks
bkmr edit 123 --force-db

Update Command

Update Fields:

# Update title
bkmr update --title "New Title" 42

# Add tags
bkmr update -t newtag 42

# Remove tags
bkmr update -n oldtag 42

# Update description
bkmr update --description "New description" 42

# Bulk update: add tag to multiple bookmarks
bkmr update -t production $(bkmr search -t deploy,app --np)

Managing Tags

View Tags

List All Tags:

# Show all tags with usage counts
bkmr tags

# Output:
python (45)
docker (32)
rust (28)
_snip_ (156)
_shell_ (48)
kubernetes (23)

Bulk Tag Operations

Add/Remove Tags in Bulk:

# Add 'reviewed' tag to all Python snippets
bkmr update -t reviewed $(bkmr search -t python,_snip_ --np)

# Remove 'draft' tag from completed docs
bkmr update -n draft $(bkmr search -t docs,complete --np)

# Replace tag across bookmarks
for id in $(bkmr search -t javascript --np); do
    bkmr update -n javascript -t js "$id"
done

Deleting Content

Delete Bookmarks:

# Delete by ID
bkmr delete 42

# Delete with confirmation
bkmr delete 42  # Prompts: "Delete bookmark 42? (y/N)"

# Bulk delete (use with caution)
bkmr delete $(bkmr search -t deprecated --np)

File Import

Basic Import

Import Files with Frontmatter:

# Import single file
bkmr import-files ~/scripts/backup.sh

# Import multiple files
bkmr import-files ~/scripts/backup.sh ~/scripts/deploy.sh

# Import entire directory
bkmr import-files ~/scripts/

# Recursive import with .gitignore support
bkmr import-files ~/projects/scripts/  # Respects .gitignore automatically

Frontmatter Format

YAML Frontmatter:

---
name: "Database Backup Script"
tags: ["database", "backup", "automation"]
type: "_shell_"
---
#!/bin/bash
# Script content here
pg_dump mydb | gzip > backup_$(date +%Y%m%d).sql.gz

Hash-Style Frontmatter:

#!/bin/bash
# name: Database Backup Script
# tags: database, backup, automation
# type: _shell_

# Script content here
pg_dump mydb | gzip > backup_$(date +%Y%m%d).sql.gz

Base Path Import

Portable File Paths:

# Import with base path for portability
bkmr import-files ~/scripts/backup.sh --base-path SCRIPTS_HOME

# Stored as: $SCRIPTS_HOME/backup.sh (portable across machines)
# Not as: /Users/username/scripts/backup.sh (machine-specific)

# Configure base paths in ~/.config/bkmr/config.toml:
# [base_paths]
# SCRIPTS_HOME = "$HOME/scripts"
# DOCS_HOME = "$HOME/documents"

Update Imports

Incremental Updates:

# Update changed files
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --update

# Detects:
# ✅ Content changes (SHA-256 hash)
# ✅ Metadata changes (frontmatter)
# ✅ Path changes (file moved)

# Preview changes first
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --update --dry-run

# Delete bookmarks for missing files
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --delete-missing

Template Interpolation

Basic Templates

Date and Time:

# Current date
bkmr add "Backup {{ current_date | strftime('%Y-%m-%d') }}" backup,_shell_ --title "Daily Backup"

# Timestamp
bkmr add "Log {{ current_date | strftime('%Y%m%d_%H%M%S') }}" logging,_shell_ --title "Timestamped Log"

Environment Variables:

# User-specific URL
bkmr add "https://dashboard.company.com/users/{{ env('USER') }}" dashboard

# With fallback
bkmr add "API={{ env('API_KEY', 'default-key') }}" config,_env_ --title "API Config"

Shell Commands:

# Git branch
bkmr add 'Branch: {{ "git branch --show-current" | shell }}' git,_snip_ --title "Current Branch"

# Hostname
bkmr add 'Host: {{ "hostname" | shell }}' system,_snip_ --title "Hostname"

When Templates Interpolate

Automatic (No Flags):

  • ✅ FZF mode: bkmr search --fzf
  • ✅ Open action: bkmr open <id>
  • ✅ Yank action: bkmr yank <id>

Manual (Flag Required):

  • Search results: bkmr search --interpolate "backup"

See Template Interpolation for complete documentation.

Common Workflows

Daily Snippet Access

# 1. Quick fuzzy search for snippets
alias bs='bkmr search --fzf --fzf-style enhanced -t _snip_'

# Usage
bs  # Opens fuzzy finder with all snippets
# Type to filter → Select with arrows → Enter to copy

Script Execution Workflow

# 1. Generate shell function stubs
source <(bkmr search --shell-stubs)

# 2. Use scripts directly
backup-database production --incremental
deploy-app staging
monitoring-status

Documentation Workflow

# 1. Store markdown documentation
bkmr add "/path/to/docs/api.md" api,docs --type md --title "API Documentation"

# 2. Quick access
alias docs='bkmr search --fzf -t _md_'

# Usage
docs  # Select documentation → Opens in browser with TOC

Environment Switching

# 1. Store environments
bkmr add "export DB_URL=..." dev,_env_ --title "Dev Env"
bkmr add "export DB_URL=..." prod,_env_ --title "Prod Env"

# 2. Quick switching
eval "$(bkmr search --fzf -t _env_)"  # Select environment

Project-Specific Bookmarks

# 1. Tag by project
bkmr add https://jira.company.com/PROJECT-123 project-myapp,ticket
bkmr add "kubectl get pods -n myapp" project-myapp,k8s,_shell_ --title "App Pods"

# 2. Search by project
bkmr search --fzf -t project-myapp

Configuration

Essential Configuration

Generate Default Config:

bkmr --generate-config > ~/.config/bkmr/config.toml

Basic Configuration Example:

# Database location
db_url = "/Users/username/.config/bkmr/bkmr.db"

# FZF options
[fzf_opts]
height = "70%"
reverse = true
show_tags = true

# Shell script options
[shell_opts]
interactive = true

# Base paths for file import
[base_paths]
SCRIPTS_HOME = "$HOME/scripts"
DOCS_HOME = "$HOME/documents"

Environment Variables

# Database location
export BKMR_DB_URL="$HOME/.local/share/bkmr/bkmr.db"

# Shell execution mode
export BKMR_SHELL_INTERACTIVE="true"

# FZF options
export BKMR_FZF_OPTS="--height 80% --reverse"

# Editor for bookmark editing
export EDITOR="vim"

See Configuration for complete documentation.

Shell Aliases and Functions

Recommended Aliases

# Add to ~/.bashrc or ~/.zshrc

# Quick fuzzy search
alias b='bkmr search --fzf --fzf-style enhanced'

# Search snippets
alias bs='bkmr search --fzf --fzf-style enhanced -t _snip_'

# Search shell scripts
alias bsh='bkmr search --fzf -t _shell_'

# Search markdown docs
alias bd='bkmr search --fzf -t _md_'

# Quick add
alias ba='bkmr add'

# Recent bookmarks
alias br='bkmr search --descending --limit 10'

Recommended Functions

# Quick open first result
bko() {
    local id=$(bkmr search "$@" --np | head -1)
    [[ -n "$id" ]] && bkmr open "$id"
}

# Tag search
bt() {
    bkmr search --fzf -t "$1"
}

# Add snippet from clipboard
bsc() {
    pbpaste | bkmr add --stdin "$@" --type snip
}

Tips and Best Practices

Tagging Strategy

Use Hierarchical Tags:

# Language → Technology → Purpose
bkmr add "code" python,flask,api,_snip_
bkmr add "code" rust,async,network,_snip_
bkmr add "url" k8s,deployment,tutorial

Consistent System Tags:

  • _snip_ - Code snippets
  • _shell_ - Shell scripts
  • _md_ - Markdown documents
  • _env_ - Environment variables
  • _imported_ - Imported files

Search Efficiently

Tag First, Then FTS:

# More efficient
bkmr search -t python "async"

# Less efficient
bkmr search "python async"

Use FZF for Final Selection:

# Pre-filter with tags, then fuzzy select
bkmr search --fzf -t python,async

Organize Large Collections

Use Descriptive Titles:

# Good
bkmr add "code" python,_snip_ --title "Async HTTP Client with Retry"

# Avoid
bkmr add "code" python,_snip_ --title "Code"

Regular Cleanup:

# Review old bookmarks
bkmr search --ascending --limit 20

# Remove deprecated entries
bkmr delete $(bkmr search -t deprecated --np)

Related Pages

Clone this wiki locally