General Information

Stubb is a [gopher] client for the [terminal]. The application functions by printing gopher content to the terminal scrollback buffer, similar to using cat to output the contents of a file. Stubb listens for keypress events to control what actions it takes: navigate to a url, follow a link, write to file, open a new tab, forward, back, and pipe the output to a reader/pager (defaults to less). Stubb is written in Lua and has one outside dependency that can be acquired via [LuaRocks], Lua's package manager (more details in the [building] section).


Stubb is named for the character [Stubb from Moby Dick], known for his imaginative patter and good humor. This client came about with a desire for a fast and very lightweight gopher client that was still feature rich. As a result, Lua was chosen as the language (for its speed) and Stubb was given the following features: bookmarks, tabs, piping, and (for privacy) history that only remains for the session (and is cleared on quit).

Quick Start

Once installed on a system and included in the system path, a user can start the application by typing stubb into their terminal and pressing enter.

At this point you will see the command bar appear. The command bar shows you what keys to press to get help and to quit as well as what tab you are on and where in the history of that tab you are.

To visit a gopher holetype gu, for go to url. You will be prompted for the URL. Once the content loads you car read it there or type pr for pipe to reader; which will try to open the content in a pager. Links can be followed with gl, for go to link; you will then be prompted for the link id, which will be visible in the content.

To go forward or backward in history you can press b for back or f for forward.

That should get you started using Stubb at a basic level. There are many more options and features. Please read the [Documentation] section to find out more.


Gopher Support

Gopher is the sole protocol supported by Bombadillo at this time. Gopher types are implemented in a 4 tier fashion:

  1. Gophermaps are supported with all classic/standardized features
  2. Text documents are supported by being printed to the terminal scrollback buffer or piped to a reader
  3. Search is partially supported via a default search engine
  4. All other types (images, binaries, etc) are implemented as downloads

Hot Keys

Stubb is controlled via hot keys. Hot keys get combined in sequence with other hot keys to perform simple or complex actions.

-- Hot Key List --
Key Series Action
a b bookmark
a t add tab
b back
c clean the screen
d w delete bookmark
d t delete tab
f forward
g b go to bookmark
g l go to link
g t go to tab
g u go to url
h help
l b list bookmark
l t list tab
p d c pipe to disk: current
p d l pipe to disk: link
p r c pipe to reader: current
p r l pipe to reader: link
p t c pipe to tab: current
p pipe to tab: link
q quit stubb
r reload current page
s search
u update bookmark title

Misc Information

When a gophermap is loaded, links will be enumerated. Pressing G and then l will prompt you for what link you would like to follow. Links are always based on the most recently loaded url for your current tab.

File save is always based out of the home directory of the user that launched Stubb.

Getting Stubb

Stubb is written in the programming language [Lua]. Since Lua is a scripting language it does not compile to binary files. As such, users will need to have Lua running on their system. Stubb has been tested with Lua versions >= 5.1.

If the system Stubb is intended to run on does not have Lua installed (run 'lua' in the terminal to find out), it can be acquired from the Lua [downloads page]. While you are at it, you may as well get [LuaRocks] as well.

Luasocket is required. It can be acquired via luarocks with: `luarocks install luasocket`. You can also get Luasocket from its [git repo]. Using luarocks is recommended as the easier option.

That should take care of dependencies. You just need to make sure that stubb, found in [this repo], is executable and on your path and you are good to go.