Configuration

Configuration

bkmr offers flexible configuration through files, environment variables, and command-line options to customize its behavior and appearance.

Configuration Methods

bkmr loads configuration in order of precedence (highest priority first):

1. Command-line arguments - Highest priority, overrides everything
2. Environment variables - System-level configuration
3. Custom config file - Specified with --config
4. Default config file - ~/.config/bkmr/config.toml
5. Built-in defaults - Lowest priority

This means you can set defaults in config.toml and override them with environment variables or command-line flags as needed.

Configuration File

Location

Default configuration file location:

~/.config/bkmr/config.toml

Generating Default Config

Create a default configuration file:

# Generate and save default config
bkmr --generate-config > ~/.config/bkmr/config.toml

# View without saving
bkmr --generate-config

Complete Configuration Example

# Main database path
db_url = "/Users/username/.config/bkmr/bkmr.db"

# FZF fuzzy finder options
[fzf_opts]
height = "70%"
reverse = true
show_tags = true
no_url = false
show_file_info = true  # Show file metadata for imported bookmarks

# Shell script execution options
[shell_opts]
interactive = true  # Enable interactive editing before execution

# Base paths for portable file imports
[base_paths]
SCRIPTS_HOME = "$HOME/scripts"
DOCS_HOME = "$HOME/documents"
WORK_SCRIPTS = "/work/automation/scripts"
PROJECT_NOTES = "$HOME/projects/documentation"
DOTFILES = "$HOME/.config"

Using Custom Config File

Specify a different config file:

# Use custom config for this command
bkmr --config ~/work/bkmr-config.toml search python

# Use custom config with alias
alias work-bkmr='bkmr --config ~/work/bkmr-config.toml'
work-bkmr search project

Environment Variables

Core Settings

Variable	Description	Default	Example
BKMR_DB_URL	Path to SQLite database	~/.config/bkmr/bkmr.db	~/Dropbox/bkmr.db
BKMR_SHELL_INTERACTIVE	Interactive shell editing	true	false
OPENAI_API_KEY	OpenAI API key for semantic search	None	sk-...
EDITOR	Text editor for editing	vim	code -w
BKMR_FZF_OPTS	FZF options	See below	--height 80%

Environment Variable Examples

Add to your shell profile (~/.bashrc, ~/.zshrc, ~/.bash_profile):

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

# Editor (VS Code with wait flag)
export EDITOR="code -w"

# OpenAI API key (for semantic search)
export OPENAI_API_KEY="sk-your-api-key"

# Shell execution (disable interactive mode)
export BKMR_SHELL_INTERACTIVE="false"

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

FZF Configuration

The fuzzy finder interface can be customized via BKMR_FZF_OPTS environment variable or in config.toml.

Available FZF Options

Option	Description	Default
height	FZF window height	50%
reverse	Display results in reverse order	false
show_tags	Show tags in results	false
no_url	Hide URLs in results	false
show_file_info	Show file metadata for imports	true

FZF Configuration Examples

In config.toml:

[fzf_opts]
height = "80%"
reverse = true
show_tags = true
show_file_info = true

As environment variable:

# Single string with all options
export BKMR_FZF_OPTS="--height 80% --reverse --show-tags"

# Hide file metadata
export BKMR_FZF_OPTS="--no-file-info"

# Tall window with tags
export BKMR_FZF_OPTS="--height 90% --show-tags"

FZF Keyboard Shortcuts

These shortcuts work in bkmr search --fzf mode:

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

FZF Style Options

# Classic style (basic display)
bkmr search --fzf

# Enhanced style (full color)
bkmr search --fzf --fzf-style enhanced

Enhanced style provides:

• Green titles
• Yellow URLs
• Magenta tags
• Cyan actions
• Grey file info (for imported bookmarks)

Shell Script Configuration

Control how shell scripts (_shell_ type) execute.

Interactive Mode (Default)

Behavior: Present an interactive editor before execution

[shell_opts]
interactive = true

Features:

• Edit script before running
• Add/modify parameters
• Vim or Emacs bindings (auto-detected)
• Command history saved to ~/.config/bkmr/shell_history.txt

Example:

bkmr open 123
# Opens editor with:
Execute: ./deploy.sh
# You edit to: ./deploy.sh --env staging --dry-run
# Press Enter to execute

Direct Execution Mode

Behavior: Execute immediately without editing

[shell_opts]
interactive = false

# Or via environment variable
export BKMR_SHELL_INTERACTIVE=false

# Now scripts execute directly
bkmr open 123  # Runs immediately

Per-Command Override

Override global setting for specific executions:

# Force direct execution (skip editor)
bkmr open --no-edit 123

# Direct execution with arguments
bkmr open --no-edit 123 -- --env production --verbose

Editor Detection

Interactive mode automatically detects your preferred bindings:

Detection sources:

1. $ZSH_VI_MODE environment variable (zsh vi mode)
2. .inputrc file for readline settings
3. set -o vi / set -o emacs in bash
4. Defaults to emacs bindings

Base Paths Configuration

Base paths make file imports portable across machines.

Configuration

[base_paths]
SCRIPTS_HOME = "$HOME/scripts"
DOCS_HOME = "$HOME/documents"
WORK_SCRIPTS = "/work/automation"
PROJECT_HOME = "$HOME/dev/projects"

Environment Variable Expansion

Base paths support environment variables:

Variable	Expands To
$HOME	User home directory
$USER	Current username
$PWD	Current working directory
Custom	Any environment variable

Example:

SCRIPTS_HOME = "$HOME/scripts"          # → /home/user/scripts
USER_SCRIPTS = "/home/$USER/scripts"   # → /home/user/scripts
WORK_DIR = "$PWD/work"                  # → /current/dir/work

Usage

# Import with base path
bkmr import-files backup.sh --base-path SCRIPTS_HOME

# Stored as: $SCRIPTS_HOME/backup.sh (portable!)
# Not as: /home/user/scripts/backup.sh (machine-specific)

See File Import and Editing for complete documentation.

Command-Line Options

Global Options

Available for all commands:

Option	Short	Description
--debug	-d	Enable debug output (use multiple times: -d -d)
--openai		Enable OpenAI integration
--config FILE	-c	Use custom config file
--generate-config		Output default configuration
--help	-h	Show help
--version	-V	Show version

Debug levels:

bkmr -d search python       # Basic debug info
bkmr -d -d search python    # Verbose debug info
RUST_LOG=debug bkmr search  # Maximum debugging

Search Command Options

Option	Short	Description	Example
--tags	-t	All tags must match	-t python,web
--Tags	-T	Any tag must match	-T python,rust
--ntags	-n	Exclude any of these	-n deprecated
--Ntags	-N	Exclude all of these	-N old,archived
--limit	-l	Limit results	-l 10
--descending	-o	Sort descending by age
--ascending	-O	Sort ascending by age
--fzf		Fuzzy finder interface
--json		JSON output
--np		No-print (IDs only)

Database Configuration

Default Location

$HOME/.config/bkmr/bkmr.db

Custom Location

Via environment variable:

export BKMR_DB_URL="$HOME/Dropbox/bkmr.db"

Via config file:

db_url = "/Users/username/Dropbox/bkmr.db"

Creating Database

# Create at default location
bkmr create-db ~/.config/bkmr/bkmr.db

# Create at custom location
bkmr create-db ~/Dropbox/bkmr.db

# Then set environment variable
export BKMR_DB_URL=~/Dropbox/bkmr.db

Database Migrations

When upgrading bkmr, migrations run automatically:

1. Check if migrations needed
2. Create backup with date suffix (e.g., bkmr_backup_20250412.db)
3. Apply migrations
4. Verify success

Backups saved in same directory as database.

Application Directory Structure

Default directory structure:

$HOME/.config/bkmr/
├── config.toml           # Configuration file
├── bkmr.db               # Main database
├── bkmr_backup_*.db      # Automatic backups
└── shell_history.txt     # Shell command history

Fallback locations (if HOME unavailable):

1. Platform-specific data directory
2. Current directory with .bkmr/ subfolder

Advanced Configuration

Shell Aliases and Functions

Add to your shell profile for quick access:

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

# Quick add
alias ba='bkmr add'

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

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

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

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

tmux Integration

Optimize FZF for tmux:

# Add to ~/.tmux.conf or shell profile
export BKMR_FZF_OPTS="--height 80% --reverse --preview-window=right:60%"

Multiple Databases

Use different databases for different contexts:

# Work database
alias work-bkmr='BKMR_DB_URL=~/work/bkmr.db bkmr'

# Personal database
alias personal-bkmr='BKMR_DB_URL=~/personal/bkmr.db bkmr'

# Project-specific
alias project-bkmr='BKMR_DB_URL=./project-bkmr.db bkmr'

Device Synchronization

Sync database across devices using:

Git (recommended):

# On machine 1
cd ~/.config/bkmr
git init
git add bkmr.db config.toml
git commit -m "Initial bkmr database"
git push origin main

# On machine 2
git clone <repo> ~/.config/bkmr
export BKMR_DB_URL=~/.config/bkmr/bkmr.db

Cloud storage:

# Dropbox
export BKMR_DB_URL="$HOME/Dropbox/bkmr/bkmr.db"

# Google Drive
export BKMR_DB_URL="$HOME/Google Drive/bkmr/bkmr.db"

# iCloud (macOS)
export BKMR_DB_URL="$HOME/Library/Mobile Documents/com~apple~CloudDocs/bkmr/bkmr.db"

Syncthing:

# Set up Syncthing folder
export BKMR_DB_URL="$HOME/Sync/bkmr/bkmr.db"

Configuration Best Practices

1. Start with defaults:

bkmr --generate-config > ~/.config/bkmr/config.toml
# Edit only what you need

2. Use environment variables for machine-specific settings:

# In ~/.bashrc (different on each machine)
export BKMR_DB_URL="$HOME/sync/bkmr.db"  # Different sync location per machine

3. Use config file for shared settings:

# Same config file synced across machines
[fzf_opts]
height = "80%"
show_tags = true

[shell_opts]
interactive = true

4. Create context-specific aliases:

# Different contexts with different databases
alias work='BKMR_DB_URL=~/work/bkmr.db bkmr'
alias home='BKMR_DB_URL=~/personal/bkmr.db bkmr'

5. Backup configuration:

# Backup config along with database
cp ~/.config/bkmr/config.toml ~/.config/bkmr/config.toml.backup

Troubleshooting

Config file not loaded:

# Check location
ls -la ~/.config/bkmr/config.toml

# Verify syntax
bkmr --generate-config > /tmp/test.toml
# Compare with your config

Environment variables not working:

# Verify they're set
echo $BKMR_DB_URL
echo $BKMR_FZF_OPTS

# Check if they're exported
export | grep BKMR

Database not found:

# Check path
ls -la "$BKMR_DB_URL"

# Create if missing
bkmr create-db "$BKMR_DB_URL"

Related Pages

• Installation - Initial setup
• Basic Usage - Common commands
• File Import and Editing - Base paths configuration
• Shell Scripts - Shell execution configuration
• Troubleshooting - Common configuration issues