Skip to content

Basic Usage

Jump to bottom
sysid edited this page Apr 8, 2026 · 6 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"

Custom Browser/Opener:

# Always open this URL in Firefox
bkmr add https://developer.mozilla.org mozilla,docs --open-with "firefox"

# Use work browser profile
bkmr add https://jira.company.com jira,work --open-with "google-chrome --profile-directory=Work"

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:

# Must have ALL tags (AND)
bkmr search -t python,async "async"

# Must have ANY tag (OR)
bkmr search -n python,rust,go

# Exclude if has ANY of these tags
bkmr search -N deprecated,old

# Combine: must have python, exclude anything tagged beginner
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-A Clone bookmark
Ctrl-P Show bookmark details
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 automatically for _snip_ type)
bkmr open 87

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

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

Non-interactive updates to any bookmark field. For interactive editing, use bkmr edit.

Update Tags:

# Add tags
bkmr update -t newtag 42

# Remove tags
bkmr update -n oldtag 42

# Overwrite entire taglist
bkmr update -f -t python,web 42

Update Content Fields:

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

# Set description
bkmr update -d "New description" 42

# Set URL/content
bkmr update --url "https://new-url.com" 42

# Combine multiple field updates in one call
bkmr update --title "Updated" -d "New desc" --url "https://new.com" 42

Update Opener:

# Set custom opener for a URL bookmark
bkmr update --open-with "firefox" 42

# Clear custom opener (revert to default)
bkmr update --open-with "" 42

Bulk Operations:

# 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 (immediate, no confirmation prompt)
bkmr delete 42

# Delete multiple IDs
bkmr delete 42,43,44

# Bulk delete (use with caution — no undo!)
bkmr delete $(bkmr search -t deprecated --np)

Common Workflows

For file import and smart editing, see Content Types — File Import. For template interpolation, see Template Interpolation.

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

For configuration, see Configuration. For advanced shell functions and aliases, see Search and Discovery — Shell Function Examples.

Additional Commands

Show Bookmark Details

# Show one or more bookmarks by ID
bkmr show 42
bkmr show 42,43,44

# JSON output for scripting
bkmr show --json 42

Clone a Bookmark

# Create a copy of an existing bookmark
bkmr add --clone 42
# Opens editor with the cloned bookmark's data pre-filled

View Program Info

# Show configuration, database path, embedding status
bkmr info

# Show database schema
bkmr info --schema

Open Random Bookmarks

# Open 1 random URL bookmark (surprise discovery)
bkmr surprise

# Open 3 random URLs
bkmr surprise -n 3

Load Bookmarks from JSON

# Import bookmarks from a JSON array file
bkmr load-json bookmarks.json

# Preview without importing
bkmr load-json bookmarks.json --dry-run

Generate Shell Completions

# Generate completions for your shell
bkmr completion bash   > /etc/bash_completion.d/bkmr
bkmr completion zsh    > ~/.zfunc/_bkmr
bkmr completion fish   > ~/.config/fish/completions/bkmr.fish

Related Pages

bkmr

Getting Started
Using bkmr
Agent Integration
Advanced
Reference

Clone this wiki locally