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):

Command-line arguments - Highest priority, overrides everything
Environment variables - System-level configuration
Custom config file - Specified with --config
Default config file - ~/.config/bkmr/config.toml
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 = "50%"
reverse = false
show_tags = false
no_url = false
show_action = true    # Show action type indicator in FZF results
show_file_info = true # Show file metadata for imported bookmarks

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

# Embedding model for semantic search (fully local, no API keys)
[embeddings]
model = "NomicEmbedTextV15"  # 768 dims, good default
# Other options: AllMiniLML6V2 (384), BGESmallENV15 (384), BGEM3 (1024)

# 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`
`FASTEMBED_CACHE_DIR`	Embedding model cache directory	`~/.cache/bkmr/models/`	`~/models/`
`EDITOR`	Text editor for editing	`vim`	`code -w`
`BKMR_FZF_OPTS`	FZF options	See below	`--height 80%`

Note: Per-bookmark custom openers (set via --open-with) override system defaults when opening URLs and local files. See Content Types - Custom Openers for details.

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"

# Embedding model cache (optional, default: ~/.cache/bkmr/models/)
export FASTEMBED_CACHE_DIR="$HOME/.cache/bkmr/models/"

# 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_action`	Show action type indicator	`true`
`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 (shell scripts: copy `bkmr open` command)
`Ctrl-E`	Edit bookmark (smart editing)
`Ctrl-D`	Delete bookmark
`Ctrl-A`	Clone bookmark
`Ctrl-P`	Show bookmark details
`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:

$ZSH_VI_MODE environment variable (zsh vi mode)
.inputrc file for readline settings
set -o vi / set -o emacs in bash
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 Content Types — File Import 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`)
`--config FILE`	`-c`	Use custom config file
`--generate-config`		Output default configuration
`--no-color`		Disable colored output
`--help`	`-h`	Show help
`--version`	`-V`	Show version

Debug levels:

bkmr -d search python        # Basic debug info (info level)
bkmr -d -d search python     # Verbose debug info (debug level)
bkmr -d -d -d search python  # Maximum verbosity (trace level)

Colored output:

Colored output is enabled automatically when writing to an interactive terminal and disabled automatically when output is piped or redirected, so there is no separate "reduced color" mode. To force colors off even on a terminal, use either of:

bkmr search --no-color      # flag (accepted in any position, e.g. `bkmr --no-color search`)
NO_COLOR=1 bkmr search      # NO_COLOR convention (https://no-color.org/)

There is currently no config-file setting for color; the flag and the NO_COLOR environment variable are the only controls.

Search Command Options

Option	Short	Description	Example
`--tags`	`-t`	Must have ALL these tags (AND)	`-t python,web`
`--Tags`	`-T`	Exclude if has ALL these tags	`-T old,archived`
`--ntags`	`-n`	Must have ANY of these tags (OR)	`-n python,rust`
`--Ntags`	`-N`	Exclude if has ANY of these tags	`-N deprecated,old`
`--limit`	`-l`	Limit results	`-l 10`
`--descending`	`-o`	Sort descending (implies `--sort modified` if no `--sort`)
`--ascending`	`-O`	Sort ascending (implies `--sort modified` if no `--sort`)
`--sort`		Sort field: `id`, `title`, `modified` (default: `id`)	`--sort title`
`--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:

Check if migrations needed
Create backup with date suffix (e.g., bkmr_backup_20250412.db)
Apply migrations
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):

Platform-specific data directory
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

Getting Started — Initial setup
Basic Usage — Common commands
Content Types — Base paths, shell scripts, file import
Troubleshooting — Common configuration issues

bkmr

Getting Started

Using bkmr

Agent Integration

Agent Integration

Advanced

Reference

Configuration

Configuration

Configuration Methods

Configuration File

Location

Generating Default Config

Complete Configuration Example

Using Custom Config File

Environment Variables

Core Settings

Environment Variable Examples

FZF Configuration

Available FZF Options

FZF Configuration Examples

FZF Keyboard Shortcuts

FZF Style Options

Shell Script Configuration

Interactive Mode (Default)

Direct Execution Mode

Per-Command Override

Editor Detection

Base Paths Configuration

Configuration

Environment Variable Expansion

Usage

Command-Line Options

Global Options

Search Command Options

Database Configuration

Default Location

Custom Location

Creating Database

Database Migrations

Application Directory Structure

Advanced Configuration

Shell Aliases and Functions

tmux Integration

Multiple Databases

Device Synchronization

Configuration Best Practices

Troubleshooting

Related Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally