terminal-bookmarks

name

terminal-bookmarks

description

Save, tag, and fuzzy-search shell commands from the terminal. Use when you need to store a complex command for later recall, search through saved commands, execute a bookmark, manage tags, or sync bookmarks across machines. Triggers include "save this command", "bookmark command", "find my docker command", "recall command", "shell history bookmark", "tbm", or any task involving managing reusable shell commands.

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

npm install -g terminal-bookmarks

Quick Start

# 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

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

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

List all bookmarks

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

Execute

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

Edit a bookmark

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

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

Tag management

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

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

tbm config set sync-remote [e-mail]: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

# 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

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 [e-mail]: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.