Last modified: 2021-12-22 22:59

Using gc

gc (or gcs) is run from the command line with options and a URL to open.

gc [options] [url]

After the url is loaded gc enters a command loop where user commands are read and interpreted. url is expected to have the usual protocol identifiers (file, gopher, http, https or gemini). If not url

If no url is given on the command line but a home page is configured gc opens that file.

gc uses a simple interactive line interface: the user enters commands and gc executes them. gc comes without a command line editor. If you want this, use rlwrap (sudo apt-get install rlwrap):

rlwrap ./gc

Notice that Ctrl+C will end gc without a proper cleanup. That is, the temporary file that is used during a gc session is not removed.

Configuration File

When starting gc tries to read configuration options from the file .config.gc or (if that not works) ~/.config/gc/config. Empty lines or comments (lines starting with a #) are allowed. The following options are recognized:

bookmarks fn
set the bookmarks file.

enable key
enables one of gc's interface options.

home url
set the home page, which is loaded from the home command or if no url parameter is given on the command line.

Unknown option print an error message and terminate gc.

If the bookmarks file is not set gc uses ~/.config/gc/bookmarks if the configuration was read from there and .bookmarks.gc else.

Protocols and Content-Types

gc understands the following protocols / URL schemes:

Several text types can be reformatted using helper programs, which should be available.

Content Type Helper
text/html lynx
text/gemini gem2text
text/markdown md2text

gem2text and md2text come with gc and lynx is expected to be installed. For Markdown, md2text extracts only [text](url "title") links but leaves the text itself as-is.

Moving Around

Navigation is simple. Most often it starts with entering a URL at the command prompt, e.g.

> gopher://

gc loads and display the content. Gopher directory item selectors are numbered and entering the number will take you there:

> 21

opens Floodgap's "getting started" directory. Notice that each item that gc displays is paged using less and depending on the text length the display may stay in paging mode until you end this by entering q. gc is ready when you see the > prompt.

gc can render text/html (using lynx -dump) and gemtext (gmi2text utility) and extracts URL from them. These are also numbered and selected by entering their number. Links from the last content file are listed (as URLs) with gc's ref command.

Gopher directories are not considered as content but as navigation. This has the side effect that loading an item does not override the contents of the last visited gopher directory. Try these commands:

> gopher://
> gemini://
> ls

There are two more link sources and all of them are selected with their index number: the history and gopher+ attribut blocks. Each time you enter a number to open a link, gc checks which item was displayed last and takes the link from the respective object. These are the commands to display and switch to their context:

Command Function
history Displays the current session history.
ls Lists the last gopher direcctory.
page Prints the last opened content item.
plus Prints the gopher+ attributes.


gc supports a simple prev/next navigation. All files that have no special relation (set by +ADMIN.Relation) and are not downloads are numbered in the order as they appear in the directory. The commands


can be used to move around. Use :rel to display the document with a particular relation, e.g. :home.

Gopher+ servers may supply prev/next information in the +RELATION block but this is currently ignored by gc. It computes the information on its own.

The option -e pnx activates an experimental prev/next. After a document has been shown the navigator prompts for one of the available prev/next actions. Simply pressing return brings you to gc command prompt.

Command Overview

Command name that are enclosed in parenthesis can be abbreviated. Entering as much that the command can be uniquely identified is enough, e.g. pa instead of page.

reloads the current directory from the server.

goes to the previous directory.

opens link number n from the current context, which can be the current gopher directory, an item's Gopher+ plus information, references from the current item or the history. The prompt indicates the context. If a + is appended the item is opened in a new xterminal (requires X windows).

opens link number n from the current gopher directory.

loads url; see also open.

goes to the previous item.

: (disable) [ option ]

disables _option_.
modifies to current item's address to guess its directory address and load it.

: (enable) [ option ]

enables _option_.
print brief command overview.

(history) [ num | regex | clear ]
list the items in the current history (matching regex) or load entry num.

(ls) [ regex ]
list all items from the curent directory (matching regex).

(open) url
opens url, which might be relative to the current location.

print the current loaded item if it is a text item.

end gc.

list references from the current (html or gemtext) item. An item can be loaded by entering its number.

reloads the current item from the server.

save [ fn ]
save the current item to fn.

load the root (i.e. the / directory) of the current server's directory. Does not properly work with Gopher-by-HTTP.

load the previous item.

show the current item's URL.


'[ label ]
loads bookmark label.

' [ regex ]
lists all bookmarks or all bookmarks matching regex.

(mark) label [ title ]
creates a bookmark for the current item.

Commands requiring Gopher+

displays the Gopher+ information for directory item num.

opens the item's link with relation rel.

edit [num]
edits directory item num by reading an writing to the gopher+ representation "+application/markup-source".

displays the current item's Gopher+ +LINKS section.

new fn
creates and edits an empty file whicch is uploaded as fn into the current directory.

(upload) [ local [ remote ] ]
stores the local file fn as remote on the server writing the data to remote%09+PUT.

Commands requiring an X-session

opens link num in a new xterminal.

duplicate the current item into a new xterminal.

Command Line Options

Possible options are

-e key
enables gc user interface options.

-f fn
reads configuration options from fn.

-l libpath
sets the path to gc's helper program md2text etc. This is usually automaically computed.

prints gc's version and exits.

gc's current working directory is important. This is the location where is stores it bookmarks (in the file .bookmarks.gc) and its temporary file. This is only removed on clean exit, not when gc is terminated with CTRL+C or similar.


When using gc as gopher client there are some things you should know.