TELESCOPE(1) General Commands Manual TELESCOPE(1)

telescopemulti-protocol browser

telescope [-ChnSv] [-c config] [URL]

telescope is an interactive browser that supports the Finger, Gemini and Gopher protocols. telescope features tabs, a minibuffer, interactive completions, bookmarks and out-of-band TOFU verification.

The arguments are as follows:

, --colors
Show all available colors and exit.
config
Specify an alternative configuration file. By default $HOME/.config/telescope/config is loaded.
, --help
Display version and usage.
Configtest mode. Only check the configuration file for validity.
, --safe
“Safe” (or “sandbox”) mode. Prevent telescope from writing files to the disk and to acquire the lock, allowing to run multiple instances at the same time. telescope still loads the session file and the custom about pages.
, --version
Display version.

telescope interface is divided into four areas: the tabline, the body, the modeline and the echoarea/minibuffer.

The tabline is always at the top of the screen and displays the tabs separated by a vertical line. When there are more tabs than the size of the window allow to display, the characters ‘<’ or ‘>’ are shown at the start/end of the tabline to indicate that there are more tabs in that direction.

The body occupies the majority of the visible area. It contains the current page and optionally a side window.

The modeline is the second to last row of the screen. It shows some information about the page: a spinner when the page is loading, the trust level, the document type, the scroll offset and the URL.

The echoarea is usually the last line of the screen. Messages are often showed there, and link addresses too. The echoarea is also used to obtain input from the user. When commands like swiper or link-select are invoked, the minibuffer area grows to show possible completions.

telescope aims to use the “Trust, but Verify (where appropriate)” approach for TOFU (“Trust On First Use”). The idea is to define three level of verification for a certificate:

untrusted
(‘!’) the server fingerprint does NOT match the stored value.
trusted
(‘v’) the server fingerprint matches the store one.
verified
(‘V’) the fingerprint matches and has been verified out-of-band.

The trust level of the page is indicated in the modeline with the indicated character.

Most of the time the “trusted” level is enough, but where is appropriate users should be able to verify out-of-band the certificate.

At the moment, there is no built-in support for an out-of-band verification though.

The following protocols are supported:

about:
About pages are telescope internal page. See about:about for a list of all these pages.
file://
File types know to telescope, such as .gmi, .gemini, .txt, .md, .markdown, .diff or .patch, can be viewed inside the application. Types of local files are detected solely based on the file extension. On some systems, such as OpenBSD, only files inside special directories (like /tmp or ~/Downloads) are available.
finger://
Finger URLs are interpreted as follows:
  • the host is determined by the host name portion of the URL
  • if the user portion of the URL is provided, it's interpreted as the user to finger, otherwise the path component will be used
thus finger://user@hostname and finger://hostname/user are treated as the same URL.
gemini://
Gemini is fully supported, with the exception of client-certificates.
gopher://
Gopher support is limited to items type 0, 1 and 7. All text is assumed to be encoded in UTF-8 (or ASCII).

User-entered URLs, given as argument on the command line or entered with load-url, are intepreted with a simple heuristic:

During the startup, telescope reads the configuration file at ~/.config/telescope/config or ~/.telescope/config.

It's possible to load a custom configuration file using the -c flag.

telescope will also load a file called config-TERM, where “TERM” is the name of the terminal type (i.e. the TERM environment variable), if it exists.

The format of the configuration file is fairly flexible. The current line can be extended over multiple ones using a backslash (‘\’). Comments can be put anywhere in the file using a hash mark (‘#’), and extend to the end of the current line, but backslashes can't be used to extend comments over multiple lines.

The following constructs are available:

map key cmd
Bind key to the function cmd in the keymap map. Valid values for map are “global-map” (i.e. when the user is viewing a page) and “minibuffer-map” (i.e. when the minibuffer has the focus.) key follows the same syntax described in DEFAULT KEY BINDINGS and all the possible functions are listed in INTERACTIVE COMMANDS.
proto via url
Use url as proxy for all URLs with protocol proto. url must be a Gemini URI without path, query and fragment component.
opt = val
Set the option opt to the value val. Valid options are:

autosave
(integer) If greater than zero, save the session after the specified amount of seconds after some events happens (new or closed tabs, visited a link ...) Defaults to 20.
dont-wrap-pre
(integer) If nonzero, don't wrap preformatted blocks. Defaults to 0.
download-path
(string) The default download path. Defaults to /tmp.
emojify-link
(integer) If nonzero, when the text of a link starts with an emoji followed by a space, use that emoji as line prefix. Defaults to 1.
enable-colors
(integer) If nonzero, enable colours. Defaults to 0 if NO_COLORS is set, 1 otherwise.
fill-column
(integer) If greater than zero, lines of text will be formatted in a way that don't exceed the given number of columns. Defaults to 80.
hide-pre-blocks
(integer) If nonzero, hide by default the body of the preformatted blocks. Defaults to zero. push-button can be used to toggle the visibility per-block.
hide-pre-closing-line
(integer) If nonzero, hide the closing line of preformatted blocks. Defaults to 0.
hide-pre-context
(integer) If nonzero, hide the start and end line of the preformatted blocks. If both hide-pre-context and hide-pre-blocks are nonzero, preformatted blocks are irremediably hidden. Defaults to zero.
new-tab-url
(string) URL for the new tab page. Defaults to “about:new”.
olivetti-mode
(integer) If nonzero, enable olivetti-mode Defaults to 1.
set-title
(integer) If nonzero, set the terminal title to the page title. Defaults to 1.
tab-bar-show
(integer) If tab-bar-show is -1 hide the tab bar permanently, if 0 show it unconditionally. If it's 1, show the bar only when there is more than one tab. Defaults to 1.
name option
Change the styling of the element identified by name. Multiple options may be specified within curly braces. Valid style identifiers are:
line
the area outside the lines in the body of the page.
line.compl
the completions.
line.compl.current
the current completion.
line.help
text in the *Help* buffer.
line.download.ongoing
an ongoing download
line.download.done
a completed download
line.download.info
informational text in the *Downloads* buffer.
line.text
text lines.
line.link
link lines.
line.title1..3
headings
line.item
item lines.
line.quote
quotes.
line.pre.start
the heading of a preformatted block.
line.pre
the content of a preformatted block.
line.pre.end
the closing line of a preformatted block.
download
the download pane
minibuffer
the minibuffer.
modeline
the modeline.
tabline
the tabline.
tabline.tab
the non-focused tabs.
tabline.current
the focused tab.

Valid options are:

prefix [line [trail]]
Sets the text attributes. If only one value is given, line and trail default to that; if two values are given then trail defaults to prefix. Each attribute is a comma-separated list of keywords:
no attributes.
best highlighting mode for the terminal.
underlines the text.
reverses background/foreground colors.
makes the text blinking.
half bright.
extra bright or bold.

Only the style identifiers with the “line.” prefix accept up to three attributes. The other will only use the first one given.

prefix [line [trail]]
Sets the background color. Follows the same behaviour as attr regarding the optional parameters. The colour is one of black, red, green, yellow, blue, magenta, cyan and white; colour0 to colour255 (or color0 to color255) from the 256-colour set; default for the default colour.
prefix [line [trail]]
Sets the foreground color. It behaves just like bg.
prfx [cont]
Sets the prefix for the current line type to prfx and cont as the prefix for the continuation lines (i.e. when a long line gets wrapped.) If cont is not given its value will be the same of prfx.

The default key bindings are very similar to GNU Emacs, but care has been taken to include also bindings familiar for vi(1) and “CUA” users. In the following examples, C-x means Control-x, M-x means Meta-x, where the Meta key may be either a special key on the keyboard or the ALT key; otherwise ESC followed by the key X works as well, and C-M-x means to press the key X together with both Control and Meta.

Keys are usually a single character, like ‘p’ or ‘n’, but some special keys are accepted as well.

<up>
Up arrow
<down>
Down arrow
<left>
Left arrow
<right>
Right arrow
<prior>
Previous page/Page up
<next>
Next page/Page down
<home>
Home
<end>
End
<f0> thru <f63>
Function keys
del or backspace
Backspace
esc
Escape
space or spc
Space
enter or ret
Enter
tab
Tab
backtab
Depends on the configuration of the terminal emulator; usually shift tab.

C-p
previous-line
C-n
next-line
C-f
forward-char
C-b
backward-char
M-{
backward-paragraph
M-}
forward-paragraph
C-a
move-beginning-of-line
C-e
move-end-of-line
M-v, M-space
scroll-up
C-v, space
scroll-down
M-<
beginning-of-buffer
M->
end-of-buffer
C-x C-c
kill-telescope
C-g
clear-minibuf
M-x
execute-extended-command
C-c {
dec-fill-column
C-c }
inc-fill-column
C-c p
previous-heading
C-c n
next-heading
>
load-url
<
load-current-url
C-x C-f
load-url
C-x M-f
load-current-url
C-x o
other-window
C-x t 0
tab-close
C-x t 1
tab-close-other
C-x t 2
tab-new
C-x t o
tab-next
C-x t O
tab-previous
C-x t m
tab-move
C-x t M
tab-move-to
B, C-M-b
previous-page
F, C-M-f
next-page
<f7> a
bookmark-page
<f7> <f7>
list-bookmarks
C-z
suspend-telescope

vi(1)-like keys

k
previous-line
j
next-line
l
forward-char
h
backward-char
{
backward-paragraph
}
forward-paragraph
^
move-beginning-of-line
$
move-end-of-line
K
scroll-line-up
J
scroll-line-down
g g
beginning-of-buffer
G
end-of-buffer
g D
tab-close
g N
tab-new
g t
tab-next
g T
tab-previous
g M-t
tab-move
g M-T
tab-move-to
H
previous-page
L
next-page
q
kill-telescope
ESC
clear-minibuf
:
execute-extended-command

<up>
previous-line
<down>
next-line
<right>
forward-char
<left>
backward-char
<home>
move-beginning-of-line
<end>
move-end-of-line
<prior>
scroll-up
<next>
scroll-down
C-w
tab-close
C-t
tab-new
M-<prior>
tab-previous
M-<next>
tab-next
M-<left>
previous-page
M-<right>
next-page
<f5>
reload-page
r
reload-page

<f1>
toggle-help
enter
push-button
M-enter
push-button-new-tab
M-tab
previous-button
backtab
previous-button
tab
next-button
M-t
tab-select
[
tab-previous
]
tab-next
M-[
tab-move-to
M-]
tab-move
M-l
link-select
M-/
swiper

enter
mini-complete-and-exit
C-g
mini-abort
ESC
mini-abort
C-d
mini-delete-char
del
mini-delete-backward-char
backspace
mini-delete-backward-char
C-h
mini-delete-backward-char
C-b
backward-char
C-f
forward-char
<left>
backward-char
<right>
forward-char
C-e
move-end-of-line
C-a
move-beginning-of-line
<end>
move-end-of-line
<home>
move-beginning-of-line
C-k
mini-kill-line
M-p
mini-previous-history-element
M-n
mini-next-history-element
C-p
previous-completion
C-n
next-completion
<up>
previous-completion
<down>
next-completion
tab
insert-current-candidate
M-<
mini-goto-beginning
M->
mini-goto-end

Follows the documentation for the interactive commands. These commands can be bound to a key or executed with execute-extended-command.

Move point one character backward.
Move point one paragraph backward.
Move point to the beginning of the buffer.
Move point to the end of the buffer.
Move point one character forward.
Move point one paragraph forward.
Copy the current selection text as minibuffer input.
Move point at the beginning of the current (visual) line.
Move point at the end of the current (visual) line.
Move point to the next link.
Select the next completion.
Move point to the next heading.
Move point to the next (visual) line, in the same column if possible.
Move point to the previous link.
Select the previous completion.
Move point to the previous heading.
Move point to the previous (visual) line.
Save a page in the bookmark file. It preloads the minibuffer with the current URL.
Load the bookmarks page.
Close the current tab.
Close all tabs but the current one.
Move the current tab after the next one, wrapping around if needed.
Move the current tab before the previous one, wrapping around if needed.
Open a new tab.
Focus next tab, wrapping around eventually.
Focus the previous tab, wrapping around eventually.
Switch to a tab using the minibuffer.

Clear the echo area.
Decrement fill-column by two.
Execute an internal command.
Quit telescope.
Increment fill-column by two.
Select and visit a link using the minibuffer.
Edit the current URL.
Prompt for an URL.
Go forward in the page history.
Toggle olivetti mode (i.e. horizontal centering of the lines of the window.)
Select the other window.
Go backward in the page history.
Follow link at point, or toggle the visibility of the following preformatted block if called when the cursor is on the heading of the block.
Follow link at point in a new tab.
Redraw the screen, useful if some background program messed up the display.
Reload the current page.
Scroll down by one visual page.
Scroll down by one line.
Scroll up by one line.
Scroll up by one visual page.
Suspend the current telescope session.
Jump to a line using the minibuffer.
Jump to a heading using the minibuffer.
Toggle side window with help about available keys and their associated interactive command.
Toggle the wrapping of preformatted blocks.

Abort the current minibuffer action.
Complete the current minibuffer action.
Delete the character before the point.
Delete the character after the point.
Select the first completion, if any.
Select the last completion, if any.
Delete from point until the end of the line.
Load the previous history element.
Load the next history element.

The following aliases are available during execute-extended-command:

and wq

When telescope is started, it inspects the following environment variables:

The user's login directory.
To decide whether to use colors or not. The content of the variable doesn't matter.
The user's terminal name.
, XDG_CONFIG_HOME, XDG_DATA_HOME
If defined can alter the default location of the files used.

By default telescope follows the XDG Base Directory Specification. However, if ~/.telescope exists, XDG is ignored and all the files are stored inside it. The usage of XDG_CACHE_HOME, XDG_CONFIG_HOME and XDG_DATA_HOME can further alter the location of these files.

~/.config/telescope/config
Default configuration file.
~/.local/share/telescope/pages/about_*.gmi
Overrides for built-in about: pages.
~/.local/share/telescope/bookmarks.gmi
Bookmarks file.
~/.local/share/telescope/known_hosts
Hash of the certificates for all the known hosts. Each line contains three fields: hostname with optional port number, hash of the certificate and a numeric flag.
~/.cache/telescope/lock
Lock file used to prevent multiple instance of telescope from running at the same time.
~/.cache/telescope/session
The list of tabs from the last session. Every line identifies a tab and contains three space-separated fields: the full URL, a comma-separated list of attributes and the cached title. Is written by kill-telescope and loaded during startup.

It's possible to browse “the small web” (i.e. simple websites) by using programs like the duckling-proxy by defining a proxy in ~/.config/telescope/config:

proxy http via "gemini://127.0.0.1:1965"
proxy https via "gemini://127.0.0.1:1965"

To load telescope without any configuration

telescope -c /dev/null

XDG Base Directory Specification, https://specifications.freedesktop.org/basedir-spec/latest/.

The telescope program was written by Omar Polo <op@omarpolo.com>.

telescope assumes a UTF-8 environment and doesn't do anything to cope with other encodings. This can cause weird rendering issues if you're lucky, or possibly worst things depending on your locale and terminal emulator.

There's no UI for out-of-band certificates validation.

October 8, 2021 OpenBSD 7.0