Bookmarks

Save your most important or frequently needed commands as bookmarks for instant access — with optional labels for context, and since 0.5.1 with {{placeholders}} that are filled in when you recall them.

Quick Start

Bookmark any command by passing the full command string. Bookmarked commands are highlighted with a star indicator in search results.

suv bookmarks add "docker compose up -d"

Interactive Manager

suv bookmarks

Open the picker to search and recall bookmarks, including when no bookmarks exist yet. Press Ctrl+A to add, Ctrl+E to edit the command or label, and Ctrl+D to delete with confirmation. In Add/Edit forms, Enter advances fields and confirms on the last field; Esc cancels.

suv bookmark remains an alias. The old bookmark pick subcommand has been replaced by the bare command. Reload your shell after upgrading so the wrapper recognizes the new picker invocation.

Commands

Add a bookmark

Save a command as a bookmark. The command does not need to exist in your history database. Optionally attach a human-readable label to describe what the command does.

suv bookmarks add <COMMAND> [-l|--label <LABEL>]

Flag	Description
`-l`, `--label <LABEL>`	Optional descriptive label for the bookmark.

List bookmarks

Display all saved bookmarks with their labels (if any). Use --json for machine-readable output.

suv bookmarks list [--json]

Flag	Description
`--json`	Output bookmarks as a JSON array. Useful for scripting or integration with other tools.

Remove a bookmark

Delete a bookmark by specifying the exact command string. The underlying history entry is not affected — only the bookmark is removed.

suv bookmarks remove <COMMAND>

Print a bookmark with its placeholders filled

Since 0.5.1, suv bookmarks get prints a bookmark's command without opening a screen, filling each placeholder from --set (repeatable) or its default. It prints the command and never runs it, so it works in scripts and for agents.

suv bookmarks get <BOOKMARK> [--set <NAME=VALUE>]...

<BOOKMARK> is its label, its exact command text, or its id. A placeholder left with neither a value nor a default is an error naming it, as is a --set for a placeholder the bookmark does not have.

Pick a bookmark

Open an interactive picker over your bookmarks and recall the chosen command straight into your shell prompt, ready to edit or run — no copy-paste needed.

suv bookmarks

Type to fuzzy-filter the list, use Up/Down to move, Enter to recall the selected command, and Esc to quit. Letters such as j, k, and q are search text. With the current Zsh/Bash integration loaded, recall places the command onto your prompt; the standalone binary prints it. Picking a bookmark with placeholders first asks for their values, as described next. Ctrl+C closes the picker in one press.

Placeholders

Since 0.5.1 a bookmark can be a template:

suv bookmarks add "ssh {{user:root}}@{{host}} -p {{port:22}}" -l box
suv bookmarks                          # pick it: a popup asks for user, host, port
suv bookmarks get box --set host=db1   # prints: ssh root@db1 -p 22

{{name}} is a placeholder; {{name:default}} gives it a default — everything after the first :, verbatim. Names start with a letter or _ and continue with letters, digits, _ or -; {{ name }} is fine.
A placeholder used more than once is asked for once and filled everywhere.
\{{ is a literal {{. Anything else in double braces that is not a placeholder — {{.State.Status}} in a docker inspect -f, a {{ with no }} — is left exactly as typed.
Values are inserted verbatim: you are typing shell syntax, so quote a value with spaces or $ the way the shell needs.
Filled values are never stored.

Picking a template in suv bookmarks opens a small Fill Placeholders popup: one field per distinct placeholder, in order, each prefilled with its default, and the filled command previewed below. Tab or Enter moves to the next field (Shift+Tab back), Enter on the last puts the filled command on your prompt exactly as a plain bookmark is — it is never run — and Esc goes back to the list.

Upgrading from 0.5.0? A bookmark you saved earlier that contains a {{word}} meant literally now asks for a value when you pick it. Edit it (Ctrl+E in the picker) to read \{{word}} to keep it literal.

The MCP list_snippets tool lists your bookmarks with each one's placeholders and defaults, read-only, so an agent can fill one with suv bookmarks get … --set … rather than retyping it.

Bookmarks in the Search TUI

Bookmarks integrate directly into the interactive search interface (suv search):

Ctrl+B — toggle the bookmark status on the currently selected history entry. If the entry is not bookmarked, it becomes bookmarked; if it already is, the bookmark is removed.
Bookmarked commands display a star indicator next to the command text in the search results list, making them easy to spot at a glance.
Bookmarked status is visible in the detail preview pane (toggle with Tab).

Examples

Bookmark with a label

Add a descriptive label so you remember why you saved the command.

suv bookmarks add "docker compose up -d" -l "start dev stack"

Bookmark a deploy command

suv bookmarks add "kubectl rollout restart deployment/api" -l "restart API pods"

List all bookmarks as JSON

Print your bookmarks as JSON for inspection or scripting. This is separate from the history import/export format.

suv bookmarks list --json

Remove a bookmark

suv bookmarks remove "docker compose up -d"

A template for a deploy target

suv bookmarks add "kubectl -n {{namespace:staging}} rollout restart deployment/{{app}}" -l restart
suv bookmarks get restart --set app=api   # kubectl -n staging rollout restart deployment/api

How It Works

Bookmarks are stored in your local SQLite history database alongside your command entries. Adding a bookmark creates a lightweight association — it does not duplicate the command data. Bookmarks persist across sessions and survive updates. A full database backup includes bookmarks; suv export exports history entries only.

Tip: Use bookmarks for commands you run infrequently but need to get exactly right — deploy scripts, database migrations, complex ffmpeg invocations, or multi-flag curl requests.

Frequently Asked Questions

How do I recall a bookmarked command?

Run suv bookmarks to open an interactive picker and drop the chosen command straight onto your shell prompt, ready to edit or run. Inside the search TUI (suv search), bookmarked entries show a star indicator so you can spot them quickly.

Does removing a bookmark delete the command from my history?

No. suv bookmarks remove <COMMAND> only removes the bookmark association — the underlying history entry stays in your database untouched.

Can I add a description to a bookmark?

Yes. Pass -l / --label when adding one, for example suv bookmarks add "docker compose up -d" -l "start dev stack". The label appears alongside the command in suv bookmarks list.

Are bookmarks included when I export or move machines?

Bookmarks are stored in your local SQLite database, so use a full database backup to preserve them. History exports do not include the bookmarks table.

Can I bookmark directly while searching?

Yes. In the search TUI, press Ctrl+B to toggle the bookmark status of the currently selected entry — no need to retype the command.