terminal-bookmarks

# terminal-bookmarks (tbm)

Save and recall shell commands with tags and fuzzy search. Local SQLite storage. Shell integration for instant access.

## When to use

- Storing complex one-liners that are hard to remember
- Building a personal command library organized by tags
- Sharing commands across machines via sync
- Quickly executing a previously saved command without retyping

## Prerequisites

1. Node.js 18+ installed
2. `tbm` installed globally: `npm install -g terminal-bookmarks`
3. (Optional) `fzf` for interactive search mode
4. (Optional) Git repository configured for sync

## Installation

```bash
npm install -g terminal-bookmarks
```

## Quick Start

```bash
# Save a command
tbm save "docker build -t myapp . --no-cache" --tag docker --desc "Full rebuild"

# Search for it later
tbm search docker

# Execute by ID
tbm exec 42

# Set up shell integration (Ctrl+B to search)
eval "$(tbm shell-init zsh)"
```

## Usage Patterns

### Save a command

```bash
tbm save "git log --oneline --graph --all --decorate" --tag git
tbm save "kubectl get pods -n production -o wide" --tag k8s --tag prod --desc "List all prod pods"
```

### Search

```bash
tbm search docker         # fuzzy search
tbm search "git log"      # multi-word search
tbm search docker --interactive  # opens fzf selector
```

### List all bookmarks

```bash
tbm list                  # all, sorted by use count
tbm list --tag docker     # filter by tag
tbm list --sort saved     # sort by date added
```

### Execute

```bash
tbm exec 3         # shows command, asks confirmation
tbm exec 3 --yes   # run without confirmation
```

### Edit a bookmark

```bash
tbm edit 3                              # opens $EDITOR
tbm edit 3 --command "new command"      # update command inline
tbm edit 3 --add-tag ops                # add a tag
tbm edit 3 --remove-tag prod            # remove a tag
tbm edit 3 --desc "new description"     # update description
```

### Delete

```bash
tbm delete 7         # prompts for confirmation
tbm delete 7 --yes   # skip confirmation
```

### Tag management

```bash
tbm tags                        # list all tags with counts
tbm tags rename k8s kubernetes  # rename a tag
tbm tags delete debug           # delete tag (bookmarks kept)
```

### Export and Import

```bash
tbm export --format json --output backup.json
tbm export --format csv --output backup.csv
tbm import backup.json
tbm import backup.json --dry-run  # preview without applying
```

### Sync

```bash
tbm config set sync-remote git@github.com:you/bookmarks.git
tbm sync push    # push local bookmarks to remote
tbm sync pull    # pull from remote, merge into local
tbm sync status  # show sync state
```

### Shell integration

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

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

# Fish
tbm shell-init fish | source     # or add to config.fish
```

After setup, press Ctrl+B to open bookmark search in the current shell.

## CLI Reference

| Command | Description |
|---|---|
| `tbm save "cmd"` | Save a command |
| `tbm save "cmd" --tag name` | Save with tag (repeatable) |
| `tbm save "cmd" --desc "text"` | Save with description |
| `tbm search query` | Fuzzy search |
| `tbm search query --interactive` | Interactive fzf search |
| `tbm list` | List all bookmarks |
| `tbm list --tag name` | Filter by tag |
| `tbm exec id` | Execute a bookmark |
| `tbm exec id --yes` | Execute without confirmation |
| `tbm edit id` | Edit in $EDITOR |
| `tbm delete id` | Delete a bookmark |
| `tbm delete id --yes` | Delete without confirmation |
| `tbm tags` | List all tags |
| `tbm tags rename old new` | Rename a tag |
| `tbm tags delete name` | Delete a tag |
| `tbm export` | Export to JSON (stdout) |
| `tbm export --format csv` | Export to CSV |
| `tbm export --output file` | Export to file |
| `tbm import file` | Import from JSON |
| `tbm import file --dry-run` | Preview import |
| `tbm sync push` | Push to remote |
| `tbm sync pull` | Pull from remote |
| `tbm sync status` | Show sync state |
| `tbm stats` | Show usage statistics |
| `tbm config show` | Show config |
| `tbm config set key value` | Set config value |
| `tbm shell-init bash\|zsh\|fish` | Print shell init script |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `TBM_DB_PATH` | Database file path | `~/.local/share/terminal-bookmarks/bookmarks.db` |
| `TBM_CONFIG_PATH` | Config file path | `~/.config/terminal-bookmarks/config.json` |
| `TBM_SYNC_REMOTE` | Git remote URL for sync | (empty) |
| `TBM_SYNC_BRANCH` | Git branch for sync | `main` |
| `TBM_NO_COLOR` | Disable color output (0 or 1) | `0` |
| `TBM_DEBUG` | Enable debug logging (0 or 1) | `0` |

## Troubleshooting

### "bookmark not found"

The ID does not exist. Run `tbm list` to see all valid IDs.

### "invalid tag name"

Tag names must be lowercase letters, numbers, and hyphens only: `[a-z0-9-]`. Spaces and uppercase are not allowed.

### "sync remote not configured"

Run `tbm config set sync-remote git@github.com:you/repo.git` first.

### "cannot open database"

Check that the directory containing the DB file is writable. Run `tbm config show` to see the db_path.

### fzf not found (interactive mode falls back to list)

Install fzf: https://github.com/junegunn/fzf - or set `tbm config set interactive_ui list` to always use the numbered list fallback.