termbrowser guide: keys, bookmarks and everyday use
Everything you need after installation: how the three focus areas work, the complete key list, where bookmarks live and what to do when a page will not render.
Starting termbrowser
termbrowser
termbrowser https://en.wikipedia.org/wiki/Web_browserWith no argument it opens the built-in start page. That page is generated locally and works without a network connection, which makes it a useful home base on a server. termbrowser --version prints the version and termbrowser --help prints a short usage summary.
Three focus areas
The interface has three places where keys can go: the address bar, the toolbar and the page. The status line at the bottom always names the current one. Tab cycles between them.
- Address bar — type a URL, press Enter to load it, Esc to leave it unchanged.
- Toolbar — choose a button with the arrow keys, activate it with Enter.
- Page — scroll and use the single-key shortcuts below.
The address bar
- Press Tab until the cursor is in the top line. The current address is selected, so typing replaces it.
- Press Enter to load what you typed. Without
http://orhttps://, the browser assumeshttps://. - Ctrl-U clears the bar; Esc leaves it without loading anything.
Keyboard shortcuts
| Key | Action |
|---|---|
| Tab | Switch between address bar, toolbar and page |
| Enter | Load an address, press a button or open a link |
| ↑ ↓ / k j | Scroll one line |
| PgUp / PgDn | Scroll one page |
| g / G | Jump to the top or bottom |
| b / f | Back / forward |
| r | Reload the current page |
| l | List every link on the page |
| B | Open bookmarks (and add the current page) |
| ? | Help |
| q | Quit |
Opening a link without hunting
Press l. termbrowser shows a numbered list of every link on the page. Move with the arrow keys, press Enter to open one and Esc to close the list. This is the fastest way to follow a reference in a long article, and it works even when the link text is buried in a paragraph.
Bookmarks
Press B to open the bookmark list. The last entry, [ add current page ], adds the page you are reading. Choose any stored bookmark and press Enter to load it.
Bookmarks are kept in ~/.termbrowser_bookmarks.json as a JSON array of URLs. Because it is a plain text file, you can edit it, copy it to another machine or symlink it into your dotfiles. There is no sync service and no account.
[
"https://en.wikipedia.org/wiki/Web_browser",
"https://news.ycombinator.com/"
]Mouse, console and tmux
On terminals that report mouse events, you can click the address bar and the toolbar buttons, and scroll with the wheel. Inside tmux or screen this depends on the terminal and on whether mouse mode is enabled. On a plain Linux console, start gpm to get mouse events.
In tmux, termbrowser runs as a normal full-screen program. Keep it in its own pane or window; resizing is handled automatically through ncurses.
Troubleshooting
termbrowser says lynx is required. What do I install?
Install lynx with your package manager. On Debian or Ubuntu run sudo apt install lynx; on Fedora sudo dnf install lynx; on Arch sudo pacman -S lynx; on macOS brew install lynx.
Why do some pages look empty or broken?
termbrowser renders text through lynx. Pages that build their content with JavaScript, block text clients or depend on CSS layout can appear empty or incomplete. That is a limitation of text rendering, not a crash.
The mouse does not work on a Linux console. What now?
Run gpm (the general purpose mouse daemon) on a plain Linux console. In most terminal emulators, tmux and SSH sessions the terminal already reports mouse events, so gpm is not needed.
Can I keep bookmarks in my dotfiles?
Yes. The file is ~/.termbrowser_bookmarks.json, a plain JSON array of URLs. Symlink it into your dotfiles repository if you like.
If the program exits immediately, run it from a terminal and check the error file it writes on unexpected exceptions: /tmp/termbrowser.err. If the display is garbled, make sure TERM is set to a real terminal type such as xterm-256color; termbrowser sets this itself when TERM is empty, dumb or unknown.