Skip to content

Introduction

Rogallo Rogallo v0.6.0 │/Users/davep/develop/python/rogallo/docs/examples/features.gmi │ │Welcome to Rogallo │ │ │Rogallo is a terminal-based client for browsing Geminispace. Its key │features include: │ │•A bookmark facility (with search) │•A location history facility (with search) │•A backward/forward navigation facility │•Support for setting a home page │•Support for user input (`1x` responses), including masked inputs for sensitive fields │•Support for in-application generation of self-signed client certificates, with │persistent per-capsule management │•Support for redirections (`3x` responses) │•Copy-to-clipboard support for URIs or page contents │•Designed to work on macOS, GNU/Linux and Windows (and likely on other operating │systems that support modern Python) │•Mouse support │•A view source facility │•A trust-on-first-use (TOFU) trust facility │•Has in-application help screens │•Has an easy-to-use command palette │•Hands unknown MIME types off to the operating system │•Optional support (on by default) for ANSI escape sequences in pages │•Support for viewing local Gemtext files │•Choice of themes │•Persistent user configuration across sessions │•Fully responsive layout that adjusts dynamically to terminal resizing │ │text/gemini >Enter a URI, file, or command  f1 Help  f2 History  f3 Bookmarks  ^[ Backward  ^] Forward  f10 Quit ▏^p Commands

Rogallo is a terminal-based client for browsing Geminispace. Its key features include:

  • A bookmark facility (with search)
  • A location history facility (with search)
  • A backward/forward navigation facility
  • Support for setting a home page
  • Support for user input (1x responses), including masked inputs for sensitive fields
  • Support for in-application generation of self-signed client certificates, with persistent per-capsule management
  • Support for redirections (3x responses)
  • Copy-to-clipboard support for URIs or page contents
  • Designed to work on macOS, GNU/Linux and Windows (and likely on other operating systems that support modern Python)
  • Mouse support
  • A view source facility
  • A trust-on-first-use (TOFU) trust facility
  • Has in-application help screens
  • Has an easy-to-use command palette
  • Hands unknown MIME types off to the operating system
  • Optional support (on by default) for ANSI escape sequences in pages
  • Support for viewing local Gemtext files
  • Choice of themes
  • Persistent user configuration across sessions
  • Fully responsive layout that adjusts dynamically to terminal resizing

Note

Rogallo is primarily designed to browse content on Gemini capsules. However, in this documentation, you will mainly see it browsing files in the local filesystem. This is because the screenshots are generated when the documentation is generated, and so visiting gemini://... locations would be slow and brittle.

Installing

pipx

The application can be installed using pipx:

pipx install rogallo

uv

The application can be installed using uv:

uv tool install rogallo

If you don't have uv installed you can use uvx.sh to perform the installation. For GNU/Linux or macOS or similar:

curl -LsSf uvx.sh/rogallo/install.sh | sh

or on Windows:

powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/rogallo/install.ps1 | iex"

Once installed run the rogallo command.

Running Rogallo

Once you've installed Rogallo using one of the above methods, you can run the application using the rogallo command. A number of command line commands and switches available:

rogallo --help

usage: rogallo [-h] [-v] [-t THEME]
               {directories,dirs,d,license,licence,bindings,themes,open} ...

A terminal-based client for the Gemini Protocol.

positional arguments:
  {directories,dirs,d,license,licence,bindings,themes,open}
                        Available commands
    directories (dirs, d)
                        Show the directories created and used by Rogallo
    license (licence)   Show license information
    bindings            List commands that can have their bindings changed
    themes              List the available themes that can be used with
                        --theme
    open                Open a location

options:
  -h, --help            show this help message and exit
  -v, --version         Show version information
  -t, --theme THEME     Set the theme for the application (see `themes`
                        command for available themes)

v0.6.0

bindings

Prints the application commands whose keyboard bindings can be modified, giving the defaults too.

rogallo bindings

AddLocationToBookmarks - Add the current location to the bookmarks
    Default: ctrl+b
Backward - Move backward through history
    Default: ctrl+left_square_bracket
ChangeCommandLineLocation - Swap the position of the command line between top and bottom
    Default: ctrl+up, ctrl+down
ChangeTheme - Change the application's theme
    Default: f9
ClearCache - Clear the cache for all content
    Default: shift+f5
CopyDocumentToClipboard - Copy the current document to the clipboard.
    Default: alt+shift+c
CopyLocationToClipboard - Copy the current location to the clipboard.
    Default: ctrl+shift+c
Forward - Move forward through history
    Default: ctrl+right_square_bracket
GoHome - Go to the home page
    Default: ctrl+h
Help - Show help for and information about the application
    Default: f1, ?
JumpToCommandLine - Jump to the command line
    Default: /, ctrl+1
JumpToDocument - Jump to the document viewer
    Default: ctrl+slash, ctrl+g, ctrl+2
JumpToSidebar - Jump to the sidebar
    Default: ctrl+3
Quit - Quit the application
    Default: f10, ctrl+q
Reload - Reload the current document
    Default: ctrl+r, f5
SearchBookmarks - Search the bookmarks for a location
    Default: f7
SearchHistory - Search the history for a location
    Default: f6
SetHome - Set the home page to a specific location
    Default: alt+h
SetHomeToCurrentLocation - Set the home page to the current location
    Default: ctrl+shift+h
ToggleBookmarks - Toggle the display of the bookmarks viewer
    Default: f3
ToggleHistory - Toggle the display of the history viewer
    Default: f2
ToggleView - Toggle between rendered and source view of the document
    Default: f4

directories

rogallo directories

This prints each of the directories where Rogallo stores cache, configuration and data files. The output will look something like this:

/Users/davep/.cache/rogallo
/Users/davep/.config/rogallo
/Users/davep/.local/share/rogallo

The exact values will, of course, depend on your own environment.

licence

Prints Rogallo's licence.

rogallo licence

Rogallo - A client for the Gemini protocol for the terminal.  
Copyright (C) 2026 Dave Pearson

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along with
this program. If not, see <https://www.gnu.org/licenses/>.

open

The open command can be used to open either a Gemtext file in the local filesystem, or a connection to content on a Gemini capsule (normally a URI starting with gemini://).

rogallo open --help

usage: rogallo open [-h] location

positional arguments:
  location    The location to open

options:
  -h, --help  show this help message and exit

themes

Shows a list of all of the themes that are available.

rogallo themes

atom-one-dark
atom-one-light
catppuccin-frappe
catppuccin-latte
catppuccin-macchiato
catppuccin-mocha
dracula
flexoki
gruvbox
monokai
nord
rose-pine
rose-pine-dawn
rose-pine-moon
solarized-dark
solarized-light
textual-dark
textual-light
tokyo-night

Use the --theme switch to set a theme from the command line.

-t, --theme

Sets Rogallo's theme; this overrides and changes any previous theme choice made via the user interface.

-v, --version

Prints the version number of Rogallo.

rogallo --version

rogallo v0.6.0

Getting help

A great way to get to know Rogallo is to read the help screen. Once in the application you can see this by pressing F1.

The Rogallo help sceeen Rogallo v0.6.0 │/Users/davep/develop/python/rogallo/docs/examples/features.gmi │┌─ Help ─────────────────────────────────────────────────────────────────────────────────┐ │││ │││ │││ │Rogallo is a│Rogallo v0.6.0│ │features inc││ │││ │•A bookmark f││ │•A location h│Viewer│ │•A backward/f││ │•Support for │As well as using the common set of cursor and page keys, the following keys are│ │•Support for │available for movement within the document:│ │•Support for │▅│management │•Support for │┌──────────────────────────────┬──────────────────────────────────────────────────┐│ │•Copy-to-clip││Key│Description││ │•Designed to │├──────────────────────────────┼──────────────────────────────────────────────────┤│odern Python) │•Mouse suppor││shift+pgdn, d│Scroll down half a page││ │•A view sourc│├──────────────────────────────┼──────────────────────────────────────────────────┤│ │•A trust-on-f││j, e, ⏎│Scroll down one line││ │•Has in-appli│├──────────────────────────────┼──────────────────────────────────────────────────┤│ │•Has an easy-││f, space, z│Scroll down one page││ │•Hands unknow│├──────────────────────────────┼──────────────────────────────────────────────────┤│ │•Optional sup││G, >│Scroll to the bottom││ │•Support for │├──────────────────────────────┼──────────────────────────────────────────────────┤│ │•Choice of th││g, <, p, %│Scroll to the top││ │•Persistent u│├──────────────────────────────┼──────────────────────────────────────────────────┤│ │•Fully respon││shift+pgup, u│Scroll up half a page││ ││├──────────────────────────────┼──────────────────────────────────────────────────┤│ │││k, y│Scroll up one line││ ││├──────────────────────────────┼──────────────────────────────────────────────────┤│ │││b, w│Scroll up one page││ ││└──────────────────────────────┴──────────────────────────────────────────────────┘│ │││ │││ ││Main application keys and commands│ │││ ││The following keys and commands can be used anywhere here on the main screen.│ │││ ││┌───────────┬─────────────┬───────────────────────────────────────────────────────┐│ │││Command│Key│Description││ ││────────────────────────────────────────────────────────────────────────────────────────│ ││▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔│ ││ Okay [Esc]│ ││▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁│ │└────────────────────────────────────────────────────────────────────────────────────────┘ │text/gemini >Enter a URI, file, or command  f1 Help  f2 History  f3 Bookmarks  ^[ Backward  ^] Forward  f10 Quit ▏^p Commands

The help will adapt to which part of the screen has focus, providing extra detail where appropriate.

The command palette

Another way of discovering commands and keys in Rogallo is to use the command palette (by default you can call it with ctrl+p).

The Rogallo command palette Rogallo v0.6.0 │/Users/davep/develop/python/rogallo/docs/examples/features.gmi │ │▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ │ │Search for commands… │Rogallo is a │features inc │Add Location To Bookmarks [^b] │•A bookmark fAdd the current location to the bookmarks │•A location hChange Command Line Location [^↑] │•A backward/fSwap the position of the command line between top and bottom │•Support for Change Theme [f9] │•Support for Change the application's theme │•Support for Clear Cache [shift+f5]management │•Support for Clear the cache for all content │•Copy-to-clipCopy Document To Clipboard [alt+shift+c] │•Designed to Copy the current document to the clipboard.odern Python) │•Mouse supporCopy Location To Clipboard [shift+^c] │•A view sourcCopy the current location to the clipboard. │•A trust-on-fGo Home [^h] │•Has in-appliGo to the home page │•Has an easy-Help [f1] │•Hands unknowShow help for and information about the application │•Optional supJump To Command Line [/] │•Support for Jump to the command line │•Choice of thJump To Document [^/] │•Persistent uJump to the document viewer │•Fully responJump To Sidebar [^3] │Jump to the sidebar │Quit [f10] │Quit the application │Reload [^r] │Reload the current document │Search History [f6] │Search the history for a location │Set Home [alt+h] │Set the home page to a specific location │Set Home To Current Location [shift+^h]▅ │Set the home page to the current location │Toggle History [f2] │▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ │ │ │ │ │ │text/gemini >Enter a URI, file, or command  f1 Help  f2 History  f3 Bookmarks  ^[ Backward  ^] Forward  f10 Quit ▏^p Commands

Questions and feedback

If you have any questions about Rogallo, or you have ideas for how it might be improved, do please feel free to visit the discussion area and ask your question or suggest an improvement.

When doing so, please do search past discussions and also issues current and previous to make sure I've not already dealt with this, or don't have your proposed change already flagged as something to do.