shell-integration

# 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

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

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

### Bash

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

### Fish

```bash
# 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:

```bash
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)

```bash
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)

```bash
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`.