The Hande, Let’s Go! Quick Start Guide

Author

Ishe Chinyoka

Published

October 1, 2026

Welcome to the hande Quick Start Guide. Hande, Let’s Go!, or “hlg”, is a powerful command-line bookmark manager that helps you jump to any resource, whether on your computer or on the web, with ease.

1 Features

Hande, Let’s Go!, or hlg for short, is a powerful bookmark manager that runs in the terminal. It helps you:

  • Keep track of your favorite resources, both on the web and offline;
  • Do web searches with the results shown in the browser;
  • Bookmark shell functions and scripts;
  • Set up a category’s own home bookmark for quick access, and flag any bookmark as a search bookmark.

2 Using hande

You can use hande in one of two ways:

2.1 The Interactive Shell

Typing hande without any arguments launches the Hande shell. This is an interactive shell where you can do the following:

  • Type a bookmark’s name to open it. This is how you’d open a bookmark called “news”, if it is in the database:

    news

  • To type a command that must be run by hande itself, precede it with a colon (:). For example, to quit the shell, just type :quit, or :q for short. To list every command, type :help, or :h.

You know you are in the shell by its prompt, hlg>, shown after a welcome message.

To cancel any prompt the shell puts up without finishing it (picking a category, picking a bookmark to edit, and so on), press Ctrl-G or Esc. Either one takes you straight back to hlg>.

The advantage of the shell is that it stays around after you launch a bookmark, and is only dismissed with :q. This means you can have a long session in the terminal with your hande shell sitting there the whole time. Bookmarks work like commands: just type them to open them, with no prefix needed.

So, after the hlg> prompt:

  • Type a bookmark’s name to open it. If you are not sure of the exact name, press the TAB key to see which bookmarks begin with the characters you have typed so far. Pressing TAB with nothing typed cycles through every bookmark available to you.

  • If the bookmark has a shortcut key, just type that key and press Enter to open it.

  • You can open a bookmark in another category by typing the category name, followed by a period, then the bookmark’s name. For example, to open a bookmark called “recipes” in the “food” category, type food.recipes.

  • If the category has a shortcut key, say f for “food”, you can instead type @f followed by the bookmark’s own shortcut. This is especially handy when both the category and the bookmark have shortcut keys: if “recipes” has the shortcut key r, you can just do @fr. The last character of an @ chain is always the bookmark’s key. If the bookmark has no key, use its full name after a period instead: @f.recipes. A category key on its own, like @f, opens that category’s home bookmark.

  • To open a bookmark by one of its tags rather than its name, type a slash followed by the tag: /progressive. If more than one bookmark carries that tag, hande shows a numbered menu to choose from. Tags are covered below.

  • To open a global bookmark, type its name starting with an uppercase letter. For example, News will be opened as a global bookmark rather than a local one.

  • To run a web search, type more than one word. hande will launch your default search engine with those words as the search phrase. If you want to search for a single word only, prefix it with a question mark so hande doesn’t mistake it for a bookmark name: ?emacs searches for information on Emacs. Without the ?, a lone word is always treated as a bookmark name; a phrase of more than one word, on the other hand, is always taken as a search, with no ? needed:

    hlg> Best terminal editors

  • To search with a search engine other than the default one, type its name first, then the phrase with a ? in front of it: ddg ?the history of mathematics. The engine must be set up as a search bookmark.

  • To see the list of your local bookmarks, type :list or :l; to see the global ones, type :global-list or :g.

  • To quit, type :quit or :q.

2.2 The Direct Calls

If you would rather not use the interactive shell, you can call hande directly from your terminal instead. When you type hande followed by one or more arguments, hande launches a bookmark or a search, then gets out of your way.

2.2.1 Launching a chosen bookmark

Pass a single argument to hande to launch any bookmark in the database. For example:

hande news

launches the bookmark called “news”, if it exists in the database. There must be a bookmark by exactly that name for this to work.

You can also use a shortcut key to launch a bookmark. If you have a bookmark called “recipes” with the shortcut key r, you can launch it like this:

hande r

We cover setting shortcut keys on bookmarks below.

2.2.2 Doing a web search with a search engine

To search using a search engine, type hande followed by the search phrase. For example:

hande The golden age of literature

runs a web search for these words, using your default search bookmark.

If your search phrase is a single word, put a question mark (?) in front of it, just as you would in the shell, so hande doesn’t mistake it for a bookmark name. For example:

hande ?GOALS

runs a web search for the term “GOALS”.

To use a search engine other than the default, name its search bookmark first:

hande ddg ?the history of mathematics

3 Creating a bookmark

The bookmark is the key component of the hande engine: it tells hande how to act, whether in the shell or from the command line.

Bookmarks are stored in a bookmark file. To open that file for editing, type:

hlg> :edit

in the shell, or:

$ hande --edit-bookmarks

in your native terminal. Either way, note that it is always the working category’s bookmark file that gets opened for editing — the default category, unless you have switched to another one with :to, or named one with --category.

You can also add a single bookmark from the shell without opening the file, using :add-bookmark (or :a). Type the whole entry at the prompt:

hlg> :add-bookmark
New bookmark for the 'default' category, e.g. `guardian <@guardian.co.uk> :chrome`: news <@bbc.com>
Added to the 'default' category.

To change an existing bookmark, including renaming it, use :update (or :u): pick the bookmark, then edit its line, which is filled in for you.

3.1 The bookmark entry

A bookmark entry is one line in a bookmark file, with up to three fields:

name <location> :handler
  1. Its name,
  2. Its location, and
  3. Its handler.

The name and location are required; the handler is optional.

3.1.1 The name

The name of a bookmark is what you type like a command in the hande shell, or pass to hande on the command line as a single argument, to launch it.

  • It should describe the resource it links to;
  • It must be at least two characters long, since single characters are reserved for shortcut keys;
  • It must start and end with an alphanumeric character;
  • It must not contain the period, forward slash, colon, question mark, plus sign, star, dollar sign, or hash mark.

A bookmark can be local or global in scope.

  • A bookmark is local when it is only visible within the category (bookmark file) it was created in.
  • A bookmark is global when it is visible throughout the whole hande database, from any category.

We cover scope in more detail in the next section. In short, though: a bookmark whose first character is uppercase is global in scope, while one whose first character is lowercase is local.

3.1.2 The location

The location of a bookmark is the address it points to. A location is written inside angle brackets: <address-of-resource-here>.

The location is the most important field of a bookmark, since it:

  • Resolves the bookmark’s name to an actual resource, and
  • Determines the type of the bookmark.

There are two types of locations:

  1. A link location, and
  2. A command location.
3.1.2.2 A command location

A command location does not resolve to a resource; instead, it runs a command. This lets you bookmark a script or a one-liner command.

A command location is denoted by a colon as the first character in the location field, for example: <:command-here>.

A command location can be either the name of a script file or a one-liner:

  • For a script file, enter its name right after the colon. For example, <:analysis.py> runs the script called “analysis.py”.
  • For a one-liner, add a colon, then an exclamation mark, then the command itself. For example: <:!echo "Hello world!">. Because of this, a one-liner is the only kind of location allowed to contain embedded spaces.

A command runs right in your terminal, with its output shown as if you had typed it yourself. If it hangs, press Ctrl-C to stop it and get back to the hlg> prompt, or to your own shell for a direct call.

3.1.3 The handler

A handler is the program that opens a bookmark’s location. It’s optional.

If you leave it out, hande picks a default handler for that type of location from the configuration file: your browser for a web address, a program listed for the file’s extension, or your file manager for anything else. You only need to set a handler when you want something other than the default.

A handler is denoted by a colon, followed by the name of the program. That program must be on your $PATH for hande to find it. To add or change a bookmark’s handler from the shell, use :add-handler (or :ah).

3.2 An example bookmark entry

Here is a complete bookmark entry, using a link shortcut:

news <@news.yahoo.com> :firefox

4 Categorizing Bookmarks

Bookmarks are organized into categories. A category is simply a bookmark file: whatever name you give a file stored in the bookmarks directory under $HANDE_HOME becomes the name of that category.

So if we have three files in the ~/.hande/bookmarks directory called “main”, “electronic”, and “books”, we have three categories.

Each bookmark file can hold bookmarks related to its own subject: the “books” category, for instance, would hold bookmarks about books.

4.1 Bookmark visibility

A bookmark saved like this:

stats <@stattrek.com>

is only visible within its own category.

This means a bookmark is either local or global in scope.

To put a bookmark in the global scope, start its name with an uppercase letter. So the bookmark above can be made global like this:

Stats <@stattrek.com>

A name starting with a lowercase letter or a digit is local. A shortcut key follows the same rule: a global bookmark’s key must be uppercase, and a local bookmark’s key must be lowercase or a digit.

From the hande shell, this is even simpler: type the :move command, followed by the name of the local bookmark, then just a colon (:) as the destination. So, in the hande shell, we could instead do this:

hlg> :move stats :

Once a bookmark becomes global, it will no longer appear in its old category’s own listing — although the underlying file, and the bookmark’s location and handler, are unchanged. It is now used as a global bookmark, not a local one.

To move a bookmark from global scope back to local scope, use an underscore (_) as the destination in the hande shell. For example, to make a global bookmark called “Book” local again, do this:

hlg> :m Book _

Note that we used the short form of “move” here: :m works just as well as :move, followed by the bookmark’s name and the destination.

Bookmark visibility matters when you’re creating references, which you can read more about in the manual.

4.2 The default category

When you type a bookmark’s name on the terminal in lowercase, it is looked up as a local bookmark. The category hande searches for that name in is called the “default category”.

You set the default category in the configuration file. First create the category, then enter its name in the configuration file, under the “default-category” option.

This means the bookmark named “stats” would be looked up in the default category with:

hande stats

4.3 Working in other categories

To launch a bookmark in a category other than the global or default scope, you must fully qualify its name. This means:

  • Typing the category’s name,
  • Then a period, then
  • The bookmark’s name.

We’ll show how to do this both from the command line (a direct call) and from the hande shell.

4.3.1 Using direct calls

For example, suppose “main” is your default category, and the bookmark “stats” is actually in the bookmark file called “books”. You cannot just type hande stats.

hande would look for “stats” in the “main” category, and either fail to find it, or — if a different “stats” bookmark happens to live there too — launch the wrong one.

Instead, type hande books.stats on the terminal.

Another way, besides using a fully-qualified name, is to pass the category’s name to the --category option. So the other way to launch the “stats” bookmark is:

hande --category books stats

Use whichever method suits how you like to work.

4.3.2 From the Hande shell

Note that hlg> in the examples below is just the prompt; you do not need to type it yourself.

In the hande shell, you can simply type:

hlg> stats

and if the bookmark is in another category, you can just type books.stats and press Enter — the “stats” bookmark will open.

You can also use the :to command to switch to another category:

  • Typing :to, followed by a category’s name, switches to that category.

  • If you’re not sure of the exact name, type :to? (note the trailing question mark) and press Enter. A list of all your available categories will appear:

    • Type the first few characters of the category you want, then press Tab.
    • When you reach the category you want, press Enter.
    • Pressing Tab with nothing typed cycles through every category in the database.

  • If the category has a shortcut key, :@ followed by that key switches to it as well: :@f switches to “food”.

  • Once you switch category, the hande shell prompt changes to hlg (category-name)>, so you always know where you are in the database.

  • When you’re done with a category, typing :to (or :@) with no argument takes you back to the default category set in the configuration file.

  • Note that :e or :edit always opens the bookmark file for the working category — the one you’re currently in.

  • To see what’s in the working category, type :category-list or :c.

4.4 Subcategories

A category file can also hold subcategories: groups of bookmarks nested inside it, written with a colon and braces:

education : {
    bookshare <@bookshare.org>
}

If this is in the “web” category, the bookmark is opened as web.education.bookshare, and :to web.education switches into the subcategory. To go back up one level, type :to .., or :@. for short. Subcategories mainly keep the folder structure of bookmarks imported from a browser, so they may only hold local web-link bookmarks. The manual covers them in full.

5 Setting Other Properties on Bookmarks

You can mark certain bookmarks as special, so hande treats them differently when you use them:

5.1 Adding shortcut keys

A shortcut key is a single character that opens a bookmark without typing its name. Write it in parentheses right after the bookmark’s name:

recipes(r) <@allrecipes.com>

When the key you want is the bookmark’s own first letter, you can instead put an underscore in front of the name, and hande takes the first letter as the key. This is the same as recipes(r) above:

_recipes <@allrecipes.com>

Use the parentheses when you want a different letter, for example because the first letter is already taken. You can’t use both on the same bookmark.

To add or change a key from the shell, use :add-key (or :ak). Remember that the key’s case must match the bookmark’s scope: lowercase for local, uppercase for global.

5.2 Adding descriptions and tags

A comment line, starting with # and placed right above a bookmark, gives it a description, tags in square brackets, or both:

# The Liberal news source [left-wing progressive critical]
guardian <@guardian.co.uk>

The description is shown in category listings, and the tags are what the / trigger searches, so /progressive opens “guardian”. Each bookmark can have only one comment line. From the shell, use :add-comment (:ac) to set the description and :add-alias (:aa, :at, or :add-tag) to set the tags.

5.3 Setting up a category home bookmark

Typing . in the hande shell opens the working category’s own home bookmark.

To set a category’s home bookmark, do the following:

  • Create a new category, for example with :n or :add-category, followed by the name you want to give it.
  • Edit the newly-created bookmark file with :edit, or, from the terminal, hande --edit-bookmarks.
  • The first line of the file is the category header, marked by a star (asterisk) * as its first character. It can hold three things, each of which is optional:
    • A category shortcut key, written right after the * with no space;
    • The home bookmark’s location, inside <...>;
    • A short description of the category, which is whatever is left on the line.

Here’s an example category header:

*l <@kernel.org> These bookmarks are about Linux

Pressing . will now open this bookmark, since it’s specially recognized as the category’s home. Since the category’s key is l, @l opens it too.

A header needs at least one of these three things, so a bare * is an error. If you don’t want a header, leave the line out altogether.

Note that the category header has no option for setting a handler: it uses the default handler for this type of location as defined in the configuration file.

5.4 Setting up a search bookmark

To mark a bookmark as a search bookmark, so hande can use it to carry out searches, do the following:

  1. Create a new bookmark entry linking to the search engine;
  2. Add a trailing ? to its name, like this: bing?;
  3. Fill in the rest of the entry, including its address and, if needed, its handler;
  4. Save the bookmark file.

To make it your default search engine, open the configuration file and set the “search” option, among the general settings at the top of the file, to the exact name of the bookmark you just flagged. If you leave “search” out, hande uses its own built-in search bookmark.

Search bookmarks are always reachable from anywhere, regardless of which category file they physically live in or whether their name happens to be uppercase or lowercase — so just write the name exactly as it’s stored, with no need to qualify it with a category. For example, if your search bookmark is google? (a lowercase name), write:

search = "google"

or, if it happens to be a capitalized name like Bing?, write:

search = "Bing"

5.5 Deactivating a bookmark

To turn a bookmark off without deleting it, add a trailing - to its name. hande then skips it as if it weren’t there. Remove the dash to turn it back on.

old-project- <@old-project.example.com>

6 Configuring Hande

The other file hande uses, besides the bookmark file, is the configuration file.

Open it by typing :config (or :cfg) in the hande shell, or hande --edit-configuration from the terminal.

The file is in TOML format. It starts with general settings, such as default-category and search, followed by sections such as [protocols], which sets the default browser, file manager, and command shell. An entry looks like this:

option = <value>

where value is whatever you choose to set: usually text in quotation marks, or a boolean value (true or false) to turn something on or off.

For example, to set the default search bookmark that hande uses whenever it processes a word starting with ?, or a phrase of more than one word — whether in the shell or from the terminal — find the “search” entry in the configuration file, and set it to the exact name of your chosen search bookmark, as covered above.

7 For More Information

hande is a powerful bookmark manager. Use it to organize your digital life, linking to resources and to commands alike.

For more advanced topics, check out the detailed manual. From the shell, just type :man to open it directly (the quick-start page you’re reading now stays available under :show-help, or ? for short).

The manual covers, in detail:

  • Launching and using hande, whether as a simple CLI tool or through its shell, including shortcut-key chains;

  • Setting up bookmark entries;

  • Link shortcuts and references, including subdomain references and domain codes;

  • Editing bookmark properties, such as:

    • Adding descriptions and tags (aliases);
    • Adding shortcut keys;
    • Flagging search bookmarks; and
    • Deactivating bookmarks;

  • Working with bookmark categories and subcategories;

  • Importing bookmarks from, and exporting them to, a web browser;

  • A detailed, section-by-section walkthrough of configuring hande.

8 Supporting HLG

hande is a work of love and productivity.

If you find it helpful, and feel like giving something back, you can support its development by:

  • Sending feedback and suggestions to the developer;
  • Donating any amount, or helping cover the cost of web hosting, new computers, or AI tokens.

Thanks in advance for any support toward the development of hande’s binaries, documentation, and web hosting.

9 Author

Ishe Chinyoka, the Textsmith Hande online page.

Developing products to boost productivity.