shell-integration

name	shell-integration
description	Set up terminal-bookmarks shell integration for interactive bookmark search with a keyboard shortcut. Use when configuring the Ctrl+B keybind widget in zsh, bash, or fish, or when troubleshooting shell integration issues. Triggers include "set up shell widget", "Ctrl+B bookmark", "shell integration", "interactive search keybind", "tbm shell-init".

shell-integration

Shell widget setup for terminal-bookmarks. Binds a keyboard shortcut (default Ctrl+B) to open an interactive bookmark search that pastes the selected command into the current shell buffer.

Supported Shells

• zsh (recommended)
• bash (GNU readline)
• fish

Setup

Zsh

# Add to ~/.zshrc
eval "$(tbm shell-init zsh)"

# Or source directly
echo 'source <(tbm shell-init zsh)' >> ~/.zshrc

Bash

# Add to ~/.bashrc
eval "$(tbm shell-init bash)"

Fish

# Add to ~/.config/fish/config.fish
tbm shell-init fish | source

Verify

After reloading your shell config, press Ctrl+B. A bookmark search interface should appear (fzf picker or numbered list).

How It Works

The init script registers a shell widget:

1. Widget function calls tbm search --interactive as a subprocess
2. tbm search --interactive shows all bookmarks in fzf (or numbered list)
3. User selects a bookmark - its command text is written to stdout
4. Widget captures stdout, inserts it into the current shell buffer at the cursor position
5. User can review or edit the command before pressing Enter to run it

The selected command is never auto-executed - it is only pasted into the buffer.

Customizing the Keybind

Change ^B to another key in your config:

tbm config set shell_keybind "^G"
# then re-source your shell init

Valid keybind formats:

• ^B - Ctrl+B
• ^G - Ctrl+G
• ^X^B - Ctrl+X, then Ctrl+B (zsh/bash only)

Interactive UI Modes

fzf mode (default when fzf is installed)

tbm config set interactive_ui fzf

fzf shows bookmarks with preview. Arrow keys to navigate, Enter to select, Escape to cancel. Search works by typing.

List mode (fallback when fzf is not installed)

tbm config set interactive_ui list

Shows a numbered list. Type the number and press Enter, or press Enter with no input to cancel.

Environment Variables

Variable	Description	Default
TBM_NO_COLOR	Disable color in interactive UI (0 or 1)	0

Troubleshooting

Ctrl+B does not work

1. Check that the init script is being sourced: type _tbm_search_widget (zsh) or type _tbm_search_bash (bash)
2. Check for keybind conflicts: bindkey | grep '\^B' (zsh)
3. Reload: source ~/.zshrc

"command not found: tbm"

The tbm binary is not on PATH. Check that the global npm bin directory is in PATH. Run npm bin -g to find it.

fzf picker is empty

tbm search --interactive is working but you have no bookmarks. Run tbm save "some command" --tag test first.

Selected command is not pasted

This is a known limitation in some terminal emulators when used with bash. Try zsh instead, or set TBM_INTERACTIVE_MODE=list.