Advanced Workflows

Advanced Workflows

bkmr provides powerful features for building sophisticated workflows tailored to your specific needs. This guide explores advanced patterns for power users who want to maximize productivity.

Overview

Advanced bkmr workflows leverage:

• Tag Prefix Filtering - Create reusable search contexts
• Content-Aware Actions - Build type-specific automation
• Shell Function Stubs - Direct script execution with arguments
• FTS Column Filtering - Precise content location
• Template Variables - Dynamic, context-aware content
• JSON Output - Integration with other tools

Tag Prefix Filtering

Tag prefix filtering is one of bkmr's most powerful features, enabling you to create reusable search patterns with complex filtering logic.

Understanding Tag Prefixes

Tag prefix options allow you to specify a set of tags that will be combined with command-line specified tags, creating a union of the same tag types:

Prefix Option	Combines With	Behavior
--tags-prefix	--tags / -t	All tags must match
--Tags-prefix	--Tags / -T	Any tag must match
--ntags-prefix	--ntags / -n	None of these tags must match
--Ntags-prefix	--Ntags / -N	None of these tags may match

Why Tag Prefixes Are Powerful

Tag prefix filtering enables you to:

1. Create specialized search contexts - Pre-filter for certain content types
2. Enforce content boundaries - Automatically exclude certain content categories
3. Simplify complex queries - Combine multiple filtering strategies in shell functions
4. Build domain-specific tools - Create custom mini-applications for different use cases

Practical Examples

Smart Snippet Search Function:

b() {
    bkmr search --fzf --fzf-style enhanced \
        --Ntags-prefix _imported_ \
        --tags-prefix _snip_ \
        "metadata:${1}*"
}

What this does:

1. Searches only snippets (tag prefix: _snip_)
2. Excludes imported content (negative tag prefix: _imported_)
3. Searches only in titles starting with your search term (metadata:${1}*)
4. Uses enhanced FZF interface for better display

Usage:

# Find all Docker-related snippets
b docker

# Find all Git-related snippets
b git

# Find all Python-related snippets
b python

Documentation-Specific Searches:

# URL-only search (exclude all system-tagged content)
alias d-="BKMR_DB_URL=$HOME/docs/bm.db bkmr search \
    --Ntags-prefix _snip_,_imported_,_shell_,_md_ \
    --tags-prefix doc"

# AWS documentation search
alias d-aws="BKMR_DB_URL=$HOME/docs/bm.db bkmr search --fzf \
    --Ntags-prefix _snip_,_imported_,_shell_,_md_ \
    --tags-prefix doc,aws"

These aliases:

• Use specific database for documentation
• Exclude all system-tagged content (only plain URLs)
• Include only items tagged with "doc"
• For AWS docs, additionally filter for "aws" tag

Content-Aware Action Workflows

bkmr's smart action system can be leveraged to build powerful, type-specific automation.

System Tag Filtering

System tags like _snip_, _shell_, _md_, and _imported_ enable type-specific workflows:

# Find only shell scripts
bkmr search --tags _shell_ "deployment"

# Find markdown documentation
bkmr search --tags _md_ "project setup"

# Find code snippets
bkmr search --fzf --tags _snip_ "async"

Action-Based Workflow Functions

Create shell functions for specific workflow needs:

# Execute shell scripts related to a specific project
run-project-script() {
    bkmr search --fzf --tags _shell_,project-"$1"
}

# Execute script with arguments
run-script-with-args() {
    local script_id="$1"
    shift
    bkmr open --no-edit "$script_id" -- "$@"
}

# View documentation for a technology
view-docs() {
    bkmr search --fzf --tags _md_,"$1"
}

# Get code snippets for a language
get-snippets() {
    bkmr search --fzf --tags _snip_,"$1"
}

Usage:

# Execute scripts for specific project
run-project-script myapp

# Run script with parameters
run-script-with-args 123 --env production --dry-run

# View React documentation
view-docs react

# Get Python snippets
get-snippets python

Chaining Actions Together

Create powerful workflows by chaining multiple actions:

# Complete deployment workflow
deploy-app() {
    local env="${1:-staging}"
    local dry_run="${2:-false}"

    # Step 1: Run backup script with environment parameter
    echo "Running backup for $env environment..."
    bkmr open --no-edit 101 -- --env "$env"

    # Step 2: Run database migration
    echo "Running migrations..."
    bkmr open --no-edit 103 -- --env "$env"

    # Step 3: Deploy application
    echo "Deploying to $env..."
    if [[ "$dry_run" == "true" ]]; then
        bkmr open --no-edit 102 -- --env "$env" --dry-run
    else
        bkmr open --no-edit 102 -- --env "$env"
    fi

    # Step 4: Verify deployment
    echo "Verifying deployment..."
    bkmr open --no-edit 104 -- --env "$env"
}

# Usage: deploy-app production false

Shell Function Stubs - Direct Script Access

⚠️ IMPORTANT: The correct command is bkmr search --shell-stubs (NOT bkmr create-shell-stubs)

Shell function stubs transform your bookmarked shell scripts into callable shell functions, enabling natural command-line execution with full argument support.

Basic Shell Stubs Generation

# View all shell function stubs that would be created
bkmr search --shell-stubs

# Example output:
# backup-database() { bkmr open --no-edit 123 -- "$@"; }
# export -f backup-database
# deploy-app() { bkmr open --no-edit 124 -- "$@"; }
# export -f deploy-app
# monitoring-setup() { bkmr open --no-edit 125 -- "$@"; }
# export -f monitoring-setup

Integration Strategies

Method 1: Dynamic Loading (Recommended for Development)

# Source directly into current shell - always fresh
source <(bkmr search --shell-stubs)

# Add to your shell profile for automatic loading
echo 'source <(bkmr search --shell-stubs)' >> ~/.bashrc
echo 'source <(bkmr search --shell-stubs)' >> ~/.zshrc

Benefits:

• Always reflects current bookmarks
• Automatically includes new shell script bookmarks
• No maintenance required

Considerations:

• Small startup delay (typically <100ms)
• Requires bkmr to be available in PATH

Method 2: Static Caching (Recommended for Production)

# Generate static functions file
bkmr search --shell-stubs > ~/.config/bkmr/shell-functions.sh

# Source the cached file in your profile
echo 'source ~/.config/bkmr/shell-functions.sh' >> ~/.bashrc

# Update when you add new shell script bookmarks
alias update-shell-stubs='bkmr search --shell-stubs > ~/.config/bkmr/shell-functions.sh'

Benefits:

• Faster shell startup
• Works without bkmr in PATH
• Explicit control over updates

Considerations:

• Manual refresh needed when bookmarks change
• Potential for stale functions

Advanced Usage Patterns

Selective Function Loading

# Create functions only for specific tags
source <(bkmr search --tags _shell_,development --shell-stubs)

# Load only production scripts
source <(bkmr search --tags _shell_,production --shell-stubs)

# Load scripts for specific project
source <(bkmr search --tags _shell_,project-myapp --shell-stubs)

Function Namespace Management

# Prefix all functions to avoid conflicts
bkmr search --shell-stubs | sed 's/^/bkmr_/' > ~/.config/bkmr/namespaced-functions.sh

# Creates: bkmr_backup-database(), bkmr_deploy-app(), etc.
source ~/.config/bkmr/namespaced-functions.sh

Project-Specific Workflows

# Create project-specific shell stub files
project-stubs() {
    local project="$1"
    bkmr search --tags _shell_,"$project" --shell-stubs > ".${project}-stubs.sh"
    echo "Created .${project}-stubs.sh - source it with: source .${project}-stubs.sh"
}

# Usage
project-stubs myapp
source .myapp-stubs.sh

# Now use project-specific commands
myapp-deploy staging
myapp-backup production

Real-World Workflow Examples

DevOps Toolkit:

# Add to ~/.bashrc or ~/.zshrc
source <(bkmr search --shell-stubs)

# Now your bookmarked scripts become part of your shell environment:
backup-database production --incremental
deploy-microservice user-auth staging --canary-percentage 10
scale-cluster monitoring --nodes 5
update-certificates *.example.com --dry-run

# All with full argument support and tab completion (if configured)

Chained Workflow Using Function Stubs:

# Create deployment workflow using multiple script stubs
deploy-full() {
    local env="${1:-staging}"

    echo "Running full deployment to $env..."
    backup-database "$env"
    run-tests "$env"
    deploy-application "$env"
    verify-deployment "$env"
}

# All functions are generated from bookmarked shell scripts

FTS Column Filtering

bkmr supports column-specific full-text search using the column:term syntax for precise content location.

Available FTS Columns

• url: - Search URLs only
• metadata: - Search metadata (titles) only
• desc: - Search descriptions only
• tags: - Search tags only

Wildcard Matching

Use * for prefix searching:

# Find URLs starting with "github"
bkmr search "url:github*"

# Find titles starting with "docker"
bkmr search "metadata:docker*"

# Find descriptions containing "deploy"
bkmr search "desc:deploy*"

Advanced Column Search Patterns

Combining Column Searches:

# Find Docker entries with Compose or Swarm in description
bkmr search "tags:docker desc:compose desc:swarm"

# Find GitHub URLs with specific title prefix
bkmr search "url:github* metadata:action*"

# Find Python snippets with async in description
bkmr search --tags _snip_,python "desc:async*"

Building Smart Search Functions:

# Search by URL domain
find-domain() {
    bkmr search --fzf "url:$1*"
}

# Search by title prefix
find-title() {
    bkmr search --fzf --fzf-style enhanced "metadata:$1*"
}

# Search descriptions for patterns
find-desc() {
    bkmr search --fzf "desc:$1"
}

Advanced Environment Variable Management

The _env_ system tag enables powerful environment management workflows.

Project-Specific Environment Switcher

# Create function to switch between project environments
project-env() {
    local project=$1
    local env=${2:-dev}  # Default to dev environment

    # Search for the right environment bookmark
    echo "Loading $project $env environment..."
    eval "$(bkmr search --fzf --fzf-style enhanced --tags-prefix _env_ -t "$project","$env")"
    echo "Environment loaded successfully"
}

# Usage
project-env myapp dev      # Load myapp development environment
project-env myapp prod     # Load myapp production environment
project-env api staging    # Load API staging environment

Multi-Environment Configuration

# Store environment configurations
bkmr add "export DATABASE_URL=postgres://localhost:5432/dev
export API_URL=http://localhost:8000
export DEBUG=true" myapp,dev,_env_ --title "MyApp Dev Env"

bkmr add "export DATABASE_URL=postgres://prod-db:5432/prod
export API_URL=https://api.myapp.com
export DEBUG=false" myapp,prod,_env_ --title "MyApp Prod Env"

# Quick environment switching
eval "$(project-env myapp dev)"   # Switch to dev
eval "$(project-env myapp prod)"  # Switch to prod

Quick Content Creation

Create type-specific shortcuts for common content creation tasks:

# Quick snippet creation
bs() {
    bkmr add -e -t _snip_ "$@"
}

# Quick markdown document creation
bm() {
    bkmr add -e -t _md_ "$@"
}

# Quick shell script creation
bsh() {
    bkmr add -e -t _shell_ "$@"
}

# Quick URL bookmark
bu() {
    local url="$1"
    shift
    bkmr add "$url" "$@"
}

Usage:

bs python,async  # Open editor for new async Python snippet
bm docs,api      # Create new API documentation markdown
bsh deploy,prod  # Create new production deployment script
bu https://example.com/docs api,reference  # Quick URL bookmark

Advanced Search Contexts

Project-Specific References

proj-refs() {
    bkmr search --fzf --tags-prefix project,reference -t "$1" "$2"
}

# Usage
proj-refs frontend "react hooks"    # Frontend project React hooks references
proj-refs backend "database"        # Backend project database references
proj-refs mobile "navigation"       # Mobile project navigation references

Language-Specific Snippets

lang-snippets() {
    bkmr search --fzf --fzf-style enhanced --tags-prefix _snip_ -t "$1" "$2"
}

# Usage
lang-snippets python "decorator"    # Python decorator snippets
lang-snippets rust "async"          # Rust async snippets
lang-snippets javascript "promise"  # JavaScript promise snippets

Technology Stack Searches

# Search within technology stack
stack-search() {
    local stack="$1"
    shift
    bkmr search --fzf --tags-prefix "$stack" -t "$@"
}

# Usage
stack-search docker compose   # Docker Compose resources
stack-search k8s deployment   # Kubernetes deployment resources
stack-search aws lambda       # AWS Lambda resources

Combining Multiple Filtering Techniques

Complex Tag Combinations

# Find Python or Rust snippets NOT tagged as beginner
bkmr search --tags-prefix _snip_ -T python,rust -n beginner

# Find shell scripts for production but not deprecated
bkmr search --tags _shell_,production -n deprecated

# Find documentation that needs review
bkmr search --tags _md_,needs-review --descending --limit 10

Date-Based Filtering with Sort Direction

# Most recently added entries
recent() {
    bkmr search --descending --limit "${1:-10}"
}

# Oldest entries that need review
needs-review() {
    bkmr search --ascending --tags needs-review --limit "${1:-20}"
}

# Recent additions by tag
recent-by-tag() {
    bkmr search --descending --tags "$1" --limit 10
}

Building a Knowledge Management System

bkmr's combination of features enables building a comprehensive personal knowledge management system.

Reference Architecture

1. URLs - Web Resources

# Tagged by technology, platform, purpose
bkmr add https://docs.python.org/3/library/asyncio.html python,asyncio,reference
bkmr add https://kubernetes.io/docs/concepts/ k8s,docs,reference

2. Snippets - Reusable Code

# Tagged by language, purpose, complexity
bkmr add 'async fn fetch_data() { ... }' rust,async,network,_snip_ --title "Async Fetch"
bkmr add 'SELECT * FROM users WHERE ...' sql,query,_snip_ --title "User Query"

3. Shell Scripts - Automation

# Tagged by function, environment, technology
bkmr add '#!/bin/bash\nkubectl apply -f ...' k8s,deploy,production,_shell_ --title "Deploy to K8s"

4. Markdown Documents - Documentation

# Tagged by topic, project, status
bkmr add "# API Documentation\n..." api,docs,current,_md_ --title "API Docs"

5. Templates - Dynamic Content

# Any content type can use template variables
bkmr add "Backup {{ current_date | strftime('%Y-%m-%d') }}" backup,_shell_ --title "Daily Backup"

Optimizing Tag Structure

Develop a consistent tagging strategy:

1. Primary categories - Single-word technology tags:

• python, rust, docker, aws, k8s

2. Qualities/Properties - Descriptive attributes:

• tutorial, reference, example, advanced, beginner

3. Projects - Prefix with project-:

• project-website, project-api, project-mobile

4. Status - Current state:

• active, archived, needs-review, deprecated

5. Content Type - Handled automatically by system tags:

• _snip_, _shell_, _md_, _env_, _imported_

Balancing Tag Specificity

Examples:

❌ Too general:

bkmr add "code" code,document  # Too vague

❌ Too specific:

bkmr add "code" python3.9-asyncio-example-with-error-handling  # Too narrow

✅ Just right:

bkmr add "code" python,asyncio,example,error-handling,_snip_  # Balanced and searchable

Bulk Tag Management

# Remove 'dev' tag, keep only 'doc,java'
bkmr update -n dev $(bkmr search -t doc,java,dev --np)

# Add 'deprecated' tag to old entries
bkmr update -t deprecated $(bkmr search --ascending --limit 50 --np)

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

Advanced Markdown Features

Interactive Table of Contents

bkmr's markdown rendering includes an advanced Table of Contents (TOC) system for long documents.

TOC Features:

• Automatic generation - Extracts H1, H2, H3 headers
• Interactive navigation - Fixed left sidebar with clickable links
• Active section highlighting - Shows current reading position
• Responsive design - Mobile hamburger menu
• Smooth scrolling - Jump to any section instantly

Practical Use Cases:

API Documentation:

bkmr add "~/docs/api-reference.md" api-docs,reference,_md_ --title "API Reference"
# TOC shows: Authentication > Endpoints > Users > Posts > Comments > Error Handling

Technical Specifications:

bkmr add "# System Architecture

## Frontend
### React Components
### State Management

## Backend
### API Design
### Database Schema

## Infrastructure
### Deployment
### Monitoring" architecture,docs,_md_ --title "Architecture"

# Creates navigable architecture overview with nested sections

Meeting Notes:

bkmr add "# Weekly Team Meeting

## Agenda
### Project Updates
### Action Items
### Blockers

## Decisions
### Technical Decisions
### Process Changes" meeting-notes,_md_ --title "Team Meeting"

# TOC enables quick navigation to specific discussion topics

Best Practices for TOC-Friendly Markdown:

1. Use consistent header hierarchy:

# Main Topic (H1)
## Major Section (H2)
### Subsection (H3)
### Another Subsection (H3)
## Another Major Section (H2)

2. Descriptive header names:

✅ # Getting Started with Authentication
❌ # Auth

✅ ## Setting Up OAuth 2.0 Flow
❌ ## OAuth Setup

3. Logical document structure:

• Use H1 for main document title
• Use H2 for major sections
• Use H3 for subsections (TOC stops at H3)
• Avoid skipping header levels (H1 → H3)

Advanced File Import Patterns

File Quickview with Metadata Enrichment

Store file contents as interpolated snippets for quick viewing:

# Add Python script as snippet with dynamic content
bkmr add "{{ \"cat \$HOME/dev/scripts/deploy.py\" | shell }}" \
    python,deploy,_snip_ \
    --title "Deploy Script" \
    --description "Source: https://github.com/company/scripts"

# View it anytime - always shows current file content
bkmr search --fzf -t deploy

Benefits:

• Always shows current file content (no stale copies)
• Add metadata and tags not in file
• Quick access without navigating filesystem
• Searchable via bkmr's powerful search

Base Path Import Workflows

# Import entire script directory with base path
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --update

# Re-import to detect changes
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --update --dry-run

# Clean up deleted files
bkmr import-files ~/scripts/ --base-path SCRIPTS_HOME --delete-missing

Integration with Other Tools

JSON Output Processing

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

# Create formatted HTML report
bkmr search --json "important" | \
    jq -r '.[] | "<li><a href=\"\(.url)\">\(.title)</a></li>"' > bookmarks.html

# Export to CSV
bkmr search --json --tags project-api | \
    jq -r '.[] | [.id, .title, .url] | @csv' > api-bookmarks.csv

Combining with fzf

# Additional fzf filtering on search results
bkmr search --json "programming" | \
    jq -r '.[] | .title' | \
    fzf --preview 'bkmr show {}'

Integration with ripgrep

# Search bookmark content with ripgrep
rg-bookmarks() {
    bkmr search --json | \
        jq -r '.[] | .url' | \
        xargs -I {} echo {} | \
        rg "$1"
}

Backup and Version Control

Automated Database Backup

# Daily backup script
backup-bkmr() {
    local backup_dir="$HOME/backups/bkmr"
    local backup_file="bkmr-$(date +%Y%m%d).db"

    mkdir -p "$backup_dir"
    cp "$HOME/.config/bkmr/bkmr.db" "$backup_dir/$backup_file"

    # Keep only last 30 days
    find "$backup_dir" -name "bkmr-*.db" -mtime +30 -delete

    echo "Backup saved: $backup_dir/$backup_file"
}

# Add to crontab for daily execution
# 0 2 * * * /path/to/backup-bkmr

Git-Based Sync

# Initialize git repo for database
cd ~/.config/bkmr
git init
git add bkmr.db config.toml
git commit -m "Initial bkmr database"

# Push to remote
git remote add origin <your-repo-url>
git push -u origin main

# On other machines
git clone <your-repo-url> ~/.config/bkmr

Troubleshooting Advanced Workflows

Template Syntax Conflicts

Problem: Scripts containing Go templates (GitHub CLI, Docker, Helm) conflict with bkmr's Jinja2 processing:

# This fails when imported into bkmr
gh run list --template '{{range .}}{{.name}}{{end}}'
# Error: Template syntax error: unexpected end of variable block

Solution: Use dynamic template construction:

# Construct template at runtime to avoid {{ pattern detection
OPEN_BRACE='{'
CLOSE_BRACE='}'
TEMPLATE="${OPEN_BRACE}${OPEN_BRACE}range .${CLOSE_BRACE}${CLOSE_BRACE}..."
gh run list --template "$TEMPLATE"

Common tools with conflicts:

• GitHub CLI (gh) - Go templates
• Docker Compose - Go template variables
• Helm charts - Go templates
• Kubernetes manifests - Go template syntax
• Terraform - Go template functions

Debugging Complex Workflows

Enable debug output:

# Single debug flag
bkmr -d search --tags-prefix project --ntags code

# Double debug flag for more detail
bkmr -d -d open 123

Test tag prefix filtering:

# Verify database contains expected tags
bkmr tags

# Check system tags are correctly applied
bkmr search -t _snip_ --json | jq '.[].tags'

Test shell function stubs:

# Preview function names before sourcing
bkmr search --shell-stubs | grep '^[a-zA-Z]' | cut -d'(' -f1

# Check for conflicts with existing commands
bkmr search --shell-stubs | grep '^[a-zA-Z]' | cut -d'(' -f1 | \
    while read func; do type "$func" 2>&1 | grep -q "is a" && echo "Conflict: $func"; done

Performance Optimization

Limiting Search Results

# Limit results for better performance
fast-search() {
    bkmr search --limit 50 "$@"
}

# Focused searches with tags
bkmr search -t python,async --limit 20 "await"

Using Tag Filtering Before FTS

# More efficient: tag filter first
bkmr search -t python "authentication"

# Less efficient: FTS without tag pre-filter
bkmr search "python authentication"

Column-Specific Searches

# More efficient: column-specific
bkmr search "metadata:docker"

# Less efficient: search all columns
bkmr search "docker"

Related Pages

• Core Concepts - Understanding tags and system tags
• Search and Discovery - FTS and tag filtering
• Shell Scripts - Shell function stubs and execution
• Template Interpolation - Dynamic content
• Configuration - Advanced configuration options
• File Import and Editing - File import workflows
• Content Types - Understanding content-specific actions