PHETCH(1)

📦
version 1.2.0 · 2 versions
, in nixos 26.05

💅 phetch — quick lil gopher client ✨

okay so bestie, welcome to PHETCH(1), from the General Commands Manual section, and honestly? this is gonna be a whole vibe. buckle up 🎀

🌸 NAME 🌸

phetch — your quick lil gopher client 💖 literally the cutest way to wander the gophersphere.

✨ SYNOPSIS ✨

phetch [OPTIONS] [URL]

🦋 DESCRIPTION 🦋

phetch is a terminal client built to help you quickly navigate the gophersphere, no cap. it's got non-nonsense keyboard navigation (yes, "non-nonsense" — that's the actual word, i'm not fixing it, it's iconic), support for most Gopher features, easy-to-use TLS and Tor support, plus bookmarking and history features. it's giving main character terminal app tbh 👑

usually you start phetch with a Gopher URL, like:

phetch gopher://some-gopher-url.com

but if you don't give it a URL? it'll launch and open its default "start page" instead. and that start page can be configured to literally any URL you want. (check the CONFIG section, i gotchu 🫶)

💅 OPTIONS 💅

  • -l, --local — connect to the local Gopher server at URL 127.0.0.1:7070. local vibes only 🏠
  • -p URL, --print URL — print a rendered Gopher server response of URL and then exit. like, pretty-printed, then bye ✌️
  • -r URL, --raw URL — print the raw Gopher server response of URL and exit. no filter, no makeup, raw dogging the bytes 💀
  • -s, --tls — attempt to fetch all pages securely over TLS. secure the bag 🔒
  • -S, --no-tls — do not use TLS for connections. super useful for cancelling out an option that got set in the config file, for instance. take that, config 🙈
  • -o, --tor — make all connections using a local Tor proxy. Tor is The Onion Router. set the TOR_PROXY env variable if you wanna use an address other than the Tor default of 127.0.0.1:9050. 🧅
  • -O, --no-tor — disable Tor. onion off, bestie 🧅❌
  • -w COLUMN, --wrap COLUMN — wrap long lines in Gopher "text" views at COLUMN. default: 0 (off). no wrap, no stress ✨
  • -m PATH, --media PATH — use the program at PATH to open media files (movies and sounds). default: mpv 🎬
  • -M, --no-media — don't try to open media files. download them like regular binary Gopher items instead. just grab it and go 📥
  • -a, --autoplay — autoplay media files instead of prompting. instant gratification, periodt ⚡
  • -A, --no-autoplay — don't autoplay media files. prompt instead. consent-based media consumption ✋
  • -c FILE, --config FILE — use FILE instead of ~/.config/phetch/phetch.conf. custom config, custom life 🗂️
  • -C, --no-config — do not use any config file. feral mode 🐾
  • -t FILE, --theme FILE — use FILE for the color theme. make it pretty 🎨
  • --print-theme — print the current theme. show me the palette 👀
  • -e ENCODING, --encoding ENCODING — render text views in CP437 or UTF8 (default) encoding. choose your charset, bestie 🔤
  • -h, --help — print a help summary and exit. the classic 🫶
  • -v, --version — print version information and exit. who am i? 📌

📝 NOTES 📝

when you give it a URL, phetch shows the requested Gopher page and enters interactive mode. that's the whole flow 💫

without a URL, phetch shows a builtin dashboard with easy access to online help, bookmarks and history — and then enters interactive mode. a lil home base 🏡

✨ also important: command line options always override options set in phetch.conf. the command line is the final boss 👑

⌨️ KEYBOARD SHORTCUTS ⌨️

all single letter commands also work with the Ctrl key: e.g., h and Ctrl+h are synonyms. so you got options, iykyk 💜

  • h — go to builtin help page.
  • q — quit phetch.
  • left arrow — go back in history.
  • right arrow — go forward in history.
  • up arrow, p, k — select previous link.
  • down arrow, n, j — select next link.
  • PgUp, - — scroll up by many lines.
  • PgDn, SPACE — scroll down by many lines.
  • Number key — open/select link. 🔢
  • Enter — open current link.
  • Esc, Ctrl+c — cancel.
  • f, / — find link in page. 🔍
  • g — go to Gopher URL.
  • R — reload current URL.
  • u — edit URL.
  • y — copy URL. 📋
  • b — show bookmarks.
  • s — save bookmark. 💾
  • a — show history. (mnemonic: All pages/history)
  • r — view raw source.
  • w — toggle wide mode.
  • e — toggle encoding between UTF8 and CP437.
  • Up and down arrows — use the up and down arrows, the j and k keys, or the n and p keys to select links. phetch will scroll for you, or you can use page up and page down (or - and spacebar) to scroll by many lines at once. it's got you 🫶
  • Number keys — if there are few enough menu items, pressing a number key will open a link. otherwise, the first matching number will be selected. use Enter to open the selected link. 🔢
  • Incremental search — press f or / to activate search mode, then just start typing. phetch will look for the first case-insensitive match and try to select it. use arrow keys or Ctrl+p/Ctrl+n to cycle through matches. type-and-hunt, iconic 🔎

🔖 BOOKMARKS 🔖

there are two ways to save the URL of the current page, bestie:

  • y — copy URL. 📋
  • s — save bookmark. 💾

bookmarks get saved to the file ~/.config/phetch/bookmarks.gph — but only if the directory ~/.config/phetch/ exists. so make the folder first, ok? 🥺

  • b — view saved bookmarks. 👀
📎 the clipboard function uses pbcopy on MacOS, and xsel -sel clip on Linux. that's just how it is 💅

🕰️ HISTORY 🕰️

if you create a history.gph file in ~/.config/phetch/, every Gopher URL you open gets stored in there. automatic memory, no thoughts 🧠✨

new URLs are appended to the bottom, but they're loaded in reverse order — so when you press the a key you'll see all the most recently visited pages first. freshest at the top, periodt 🔥

and honestly? feel free to edit your history file directly, or share it with your friends! it's your data, bestie, go wild 💖

⚙️ CONFIG ⚙️

if you create a phetch.conf file in ~/.config/phetch/, it'll be automatically loaded when phetch starts. the config file supports most command line options, for your convenience, plus a few ways to customize your browsing experience. for example, phetch will always launch in TLS mode if tls yes appears in the config file — no need to pass --tls or -t on startup. set it and forget it 🫧

here's an example config with all options:

# Page to load when launched with no URL argument.
start gopher://phetch/1/home

# Always use TLS mode. (--tls)
tls no

# Connect using local TOR proxy. (--tor)
tor no

# Always start in wide mode.
wide no

# Program to use to open media files.
media mpv

# Use emoji indicators for TLS & Tor.
emoji no

# Encoding. Only CP437 and UTF8 are supported.
encoding utf8

# Wrap text at N columns. 0 = off (--wrap)
wrap 0

# How many lines to page up/down by? 0 = full screen
scroll 0

# Path to theme file, if you want to use one
theme ~/.config/phetch/dark.theme

🎨 THEMES 🎨

you can change phetch's color scheme by supplying your own theme file with --theme/-t, or by setting theme FILE in your phetch.conf. customize away, bestie 💅

you can also view the current theme with:

$ phetch --print-theme

theme files look like this:

ui.cursor white bold
ui.number magenta
ui.menu yellow
ui.text white
item.text cyan
item.menu blue
item.error red
item.search white
item.telnet grey
item.external green
item.download white underline
item.media green underline
item.unsupported whitebg red

valid colors for use in phetch themes:

bold
underline

grey
red
green
yellow
blue
magenta
cyan
white
black

darkred
darkgreen
darkyellow
darkblue
darkmagenta
darkcyan
darkwhite

blackbg
redbg
greenbg
yellowbg
bluebg
magentabg
cyanbg
whitebg

that's the whole palette, slay 🌈

🎬 MEDIA PLAYER SUPPORT 🎬

phetch includes support for opening video files (; item type) and sound files (s item type) in mpv or an application of your choice, using the -m command line flag. to test it out, visit a compatible Gopher server, or check out the "gopher types" help page by launching phetch and then pressing ctrl-h then 3. tutorial speedrun 🏃‍♀️💨

by default phetch will prompt you when you try to open a media file, but you can change this behavior by starting it with --autoplay/-a, or by setting autoplayer true in your config file. your call, bestie 🍓

👑 ABOUT 👑

phetch is maintained by chris west, and released under the MIT license.

phetch's Gopher hole:

gopher://phkt.io/1/phetch

phetch's webpage:

https://github.com/xvxx/phetch

🦋 aaaand that's the whole page! this edition is dated 1980-01-01 and lives under the PHETCH(1) name in the General Commands Manual — vintage date, immaculate vibes. go forth and gopher, bestie 💖✨🎀

📦 where this page comes from