1  Getting Started with hande

1.1 The interactive shell

Type hande with no arguments, and you land in hande’s own shell:

$ hande
Hande, Let's Go! version 1.0 (2026-10-01) -- "Your Digital Treasures"
Copyright (C) 2026 Ishe Chinyoka, the Textsmith  under the MIT license.

Type :help for help, :license for license.
hlg>

From here, you can:

  • Type a bookmark’s name and press Enter to open it. No prefix, no punctuation — just the name, exactly like typing a command.
  • Press Tab while typing a name to complete it. Press Tab with nothing typed at all to cycle through every bookmark available to you from where you’re standing.
  • Type a command, always preceded by a colon. :quit (or :q) leaves the shell. :help (or :h, or ?) lists every command.

The shell stays open between bookmarks — open one, come back, open another — until you leave it with :q. Every editing feature in this manual (adding, renaming, tagging, moving a bookmark) is a shell command, described as it comes up in the following chapters.

To cancel out of any prompt the shell puts up without finishing it — picking a category, picking a bookmark to edit, anything that waits for your answer — press Ctrl-G or Esc. Either one aborts cleanly and drops you back at hlg>.

1.2 The command line

You don’t have to enter the shell at all. Pass hande an argument directly from your regular system shell, and it opens that one bookmark and exits:

$ hande news

This is exactly equivalent to typing news at the hlg> prompt — it’s the same lookup, the same handler, the same result. Use whichever fits the moment: the shell if you’re settling in to browse and edit, the direct call if you just want one thing opened and to get back to what you were doing.

Everything from here on describes both the shell and the direct call together, since the underlying behaviour never differs between them, and calls out the rare exceptions when a feature is shell-only.

1.3 Searching with hande

To run a web search instead of opening a bookmark, type more than one word:

hlg> teach me how to divide fractions

hande sends the whole phrase to your default search engine (configured — see Chapter 7) and opens the results. A single word is always read as a bookmark name, never a search, so if you want to search for just one word, put a ? in front of it to tell hande apart:

hlg> ?photosynthesis

You can also name a different search engine on the fly, as long as it’s set up as a search bookmark of its own (see Chapter 5): put its name first, then a ? in front of the phrase:

hlg> ddg ?the history of mathematics

Both forms work identically from the command line:

$ hande ?photosynthesis
$ hande ddg ?the history of mathematics

1.4 The / alias trigger

Bookmarks can carry tags — short keywords attached alongside their description (covered fully in Chapter 5). A leading / looks a bookmark up by one of its tags instead of its name:

hlg> /progressive

If exactly one bookmark in scope carries that tag, hande opens it directly. If more than one does, you’ll see a numbered menu to choose from:

There are more than one bookmark with the alias 'progressive'
Please select one from the list below:
[Choice]    Bookmark        Description
[1] guardian        The Liberal news source
[2] techblog        A progressive tech blog
Your choice:

An alias lookup is always scoped to wherever you’re currently working — your active category if you’re in the shell (see Chapter 2), or whatever category you’ve named explicitly.

1.5 Shortcut keys

Any bookmark, and any category, can carry a single-character shortcut key, letting you skip typing the full name entirely.

1.5.1 Opening a bookmark by its own key

If a bookmark’s shortcut key is unique enough on its own, just type the key:

hlg> r

1.5.2 Chaining a category key with a bookmark key

The @ symbol chains shortcut keys together: the first character picks a category by its own key, and the last character picks a bookmark by its key within it. For a category “food” (key f) holding a bookmark “recipes” (key r):

hlg> @fr

If a category has subcategories (see Chapter 2) and they carry their own keys too, every character between the first and the last walks one subcategory level deeper. For a category “web” (key w) holding a subcategory “education” (key e) holding a bookmark “bookshare” (key b):

hlg> @web

The very last character in an @ chain is always the target bookmark’s own key — never a subcategory’s, even if a subcategory happens to share that character. This is deliberate: there’s never any ambiguity about what a chain like @web means, regardless of how your categories happen to be keyed.

A bare category key on its own, with nothing following it, opens that category’s own home bookmark (see Chapter 2):

hlg> @f

1.5.3 When you need a full name instead of a key

An @ chain is always made up of single-character keys — it never mixes in a full name. If you want to name a category by its key but a bookmark by its actual name, use a period to separate the two:

hlg> @f.recipes

Typing a period anywhere else inside an @ chain is an error, and hande will tell you so directly rather than guessing what you meant — if you want a category or bookmark by its full name rather than a key, the ordinary category.name addressing from Chapter 2 already does that without @ at all.

1.5.4 :@ — jumping straight to a category or subcategory

From inside the shell only, :@ followed by a key chain switches your working category outright, rather than opening a bookmark. It reads the entire chain as category and subcategory keys, with none held back for a bookmark — the opposite convention from the bookmark launcher’s own @ chain above. Continuing the “web / education / bookshare” example:

hlg> :@we
Switched to the 'web/education' category.

Compare this with the bookmark launcher’s @we, which would open whatever bookmark is keyed e directly inside “web” — a different destination entirely, on purpose. Whether you’re reaching for a bookmark or a place to work, the tool you reach for tells hande which one you mean.

:@ on its own, with no key chain at all, resets you to the default category — exactly like :to with no argument (see Chapter 2).

:@. is a third, narrower special case: it goes up to the parent of whatever subcategory you’re currently working in, exactly like :to .. does. Standing in “web/education/bookshare”, :@. takes you to “web/education”; from a top-level category (nowhere left to go up to), it tells you so rather than doing anything.

1.5.5 _ — starting a chain from where you already are

Both kinds of @ chain above always start from a top-level category’s own key — which means reaching a subcategory that isn’t a direct child of a top-level category means spelling out its parent’s key too, even if you’re already standing right next to it. A leading _ fixes this: it starts the chain from your current category instead of a top-level key, and is otherwise never a real shortcut key itself, so there’s no ambiguity in using it this way.

Continuing the “searches” example from earlier, suppose “searches” has its own subcategory “ai” (key a), holding a bookmark “claude” (key c). Working inside “searches” already, you don’t need to spell out “searches” itself again:

hlg (searches)> :@_a
Switched to the 'searches/ai' category.

hlg (searches)> @_ac

:@_a walks into “ai” the same way :@sa would if “searches” had a top-level key s — it just starts from wherever you already are instead. @_ac does the same for the bookmark launcher: _ takes the place of a top-level key, a walks into “ai”, and c — still, as always, the very last character — opens “claude”.

Outside the shell, there’s no “current category” to speak of (see Chapter 2), so _ there means the default category instead — $ hande @_ac behaves exactly like the shell example above whenever “searches” is your default category.