Tiny Gemini browser written in POSIX shell

f1d932f Create directory for desktop entry when installing

~chambln pushed to ~chambln/gmi git

a month ago
3 months ago


Tiny Gemini browser written in POSIX-compliant shell. Highly hackable, portable shell script under 200 lines.


  • POSIX shell and command utilities
  • openssl
  • base64
  • less
  • fzf
  • xdg-open (for following non-Gemini links)


  • Download, page through and navigate between Gemtext documents
  • Browse text/gemini documents and other files on disk
  • Follow Gemtext links numerically or by fuzzy match
  • Follow non-Gemini links using xdg-open
  • Non-text resources are downloaded and saved to disk
  • Coloured syntax highlighting of Gemtext documents


Install for all users (as root):

make install

Install for this user only:

make PREFIX=~/.local install


See gmi(1).

Pro tip: Keep your bookmarks as Gemtext links in a ‘bookmarks.gmi’ file. Here are some examples to get you started:

=> gemini://gemini.circumlunar.space/ Project Gemini homepage
=> gemini://cosine.blue/gmi/ Home page of the gmi browser

#Known issues

  • Arguably a feature but the ‘Back’ button only remembers the last resource you visited, even if you came ‘Back’ from that resource. So you cannot always return where you started by repeatedly going ‘Back’ — instead you’ll just toggle back and forth between two resources.

  • When reading non-textual data from standard input, gmi doesn’t know what the name of the "downloaded" file should be. This is undefined behaviour. At the moment it seems to use the name of the working directory so, for example ‘cd ~/Pictures && gmi - < foo.jpg’ will effectively copy the contents of foo.jpg into a newly created file named ~/Pictures/Pictures. The stdin feature was never really intended for non-textual data.

#Wishlist / to-do list

  • Key bindings for navigation using lesskey. Not sure how all this lesskey stuff works but I’m hoping we can (ab)use the numeric prefix so that, for example, pressing ‘5o’ would open link number 5. Maybe a negative argument could mean go back so many pages in the history (although browsing history remains to be implemented).

  • Pretty line wrapping of paragraphs, quotes and lists. This would involve wrapping on word boundaries and, for block quotes, repeating the "> " line prefix. This will greatly improve readability of Gemtext documents as rendered by gmi.

  • Get a line of input from the user for response codes 10-19. Bonus points for line-editing, although it may not be possible to do that portably.

  • Fix bug where gmi basically crashes when trying to write a non-text file to disk if the a file of the same name already exists.