💾 Archived View for telescope-browser.org › telescope.1.txt captured on 2024-08-24 at 23:09:21.
⬅️ Previous capture (2024-07-08)
-=-=-=-=-=-=-
TELESCOPE(1) General Commands Manual TELESCOPE(1)
NAME
telescope – multi-protocol browser
SYNOPSIS
telescope [-hnSv] [-c config] [URL]
DESCRIPTION
telescope is a browser that supports the Finger, Gemini and
Gopher protocols. telescope features tabs, a minibuffer,
interactive completions, bookmarks and client certificates.
The arguments are as follows:
-c config Specify an alternative configuration file.
By default ~/.config/telescope/config is
loaded.
-h, --help Display version, usage and exit.
-n Configtest mode. Only check the
configuration file for validity.
-S, --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.
-v, --version Display version and exit.
UI CONCEPTS
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, whether a client
certificate is in use, a warning indicator for faulty
Gemini servers, document type, the scroll offset and the
URL. When a client certificate is in use, a ‘C’ character
is showed. Some Gemini servers have buggy TLS handling but
some information might still be available. This
information could be truncated. In those circumstances, a
‘W’ character is shown.
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.
TOFU
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.
SUPPORTED PROTOCOLS
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.
gopher:// Gopher support is limited to items type 0, 1 and
7. All text is assumed to be encoded in UTF-8
(superset of ASCII).
User-entered URLs, given as argument on the command line or
entered with load-url, by default are intepreted with a
simple heuristic:
• if it's a proper absolute URL then use it as-is,
• if it starts with “./” or “/” assume it's a file://
URL,
• otherwise treat it like a hostname with protocol
default-protocol (gemini by default).
The setting load-url-use-heuristic can be used to disable
the use of heuristics.
MIME-TYPE HANDLING
Beyond the supported protocols which telescope already
understands, mime-types which telescope cannot display can
be opened using a mailcap file. By default, telescope will
look for one of the following mailcap files in the
following order:
~/.mailcap
/etc/mailcap
/usr/etc/mailcap
/usr/local/etc/mailcap
A default mailcap entry is always defined by telescope
which uses xdg-open(1) as a fallback for mime-types not
defined through a mailcap file, or if no mailcap file was
found.
Refer to RFC 1524 for more information about the structure
and format of this file. Note that telescope currently
only supports a small subset of this standard, honouring
only the needsterminal and copiousouput flags.
CONFIGURATION FILE
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:
bind 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.
proxy 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.
set 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
happened (new or closed tabs,
visited a link ...) Defaults to 20.
default-protocol
(string) The default protocol
assumed for the load-url heuristic.
Defaults to “gemini”.
default-search-engine
(string) URL of the preferred search
engine, used by the search command.
If it's a Gemini URI, the user query
will be appended as query, replacing
it if present. If it's a Gopher
URI, the user query will be sent as
gopher search parameter. No other
URI scheme are allowed.
dont-wrap-pre (boolean) If true, don't wrap
preformatted blocks. Defaults to
false.
download-path (string) The default download path.
Defaults to /tmp.
emojify-link (boolean) If true, when the text of
a link starts with an emoji followed
by a space, use that emoji as line
prefix. Defaults to true.
enable-colors (boolean) If true, enable colours.
Defaults to false if NO_COLORS is
set, true 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.
fringe-ignore-offset
(boolean) If true, the fringe
doesn't obey to olivetti-mode.
Defaults to false.
hide-pre-blocks
(boolean) If true, hide by default
the body of the preformatted blocks.
Defaults to false. push-button can
be used to toggle the visibility
per-block.
hide-pre-closing-line
(boolean) If true, hide the closing
line of preformatted blocks.
Defaults to false.
hide-pre-context
(boolean) If true, hide the start
and end line of the preformatted
blocks. If both hide-pre-context
and hide-pre-blocks are true,
preformatted blocks are irremediably
hidden. Defaults to false.
new-tab-url (string) URL for the new tab page.
Defaults to “about:new”.
load-url-use-heuristic
(boolean) If false, don't use
euristics to resolve the URLs. Non-
absolute URLs given as command line
argument will be resolved as file
system paths, load-url will resolve
as relative to the current URL.
Defaults to true.
max-killed-tabs
(integer) The maximum number of
closed tabs to keep track of,
defaults to 10. Must be a positive
number; if zero, don't save closed
tabs at all.
olivetti-mode (boolean) If true, enable
olivetti-mode. Defaults to true.
tab-bar-show (integer) If tab-bar-show is -1 hide
the tab bar permanently, if 0 show
it unconditionally. If 1, show the
bar only when there is more than one
tab. Defaults to 1.
update-title (boolean) If true, set the terminal
title to the page title. Defaults
to true.
style 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.fringe (virtual) lines draw
after the end of a
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:
attr 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:
normal no attributes.
standout best highlighting mode for
the terminal.
underline underlines the text.
reverse reverses
background/foreground
colors.
blink makes the text blinking.
dim half bright.
bold 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.
bg 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.
fg prefix [line [trail]]
Sets the foreground color. It behaves just
like bg.
prefix 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.
DEFAULT KEY BINDINGS
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.
GNU Emacs-like keys
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-x C-w write-buffer
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 u up
g r root
g h home
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
u tab-undo-close
q kill-telescope
ESC clear-minibuf
: execute-extended-command
CUA-like keys
<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
del previous-page
M-<left> previous-page
M-<right> next-page
<f5> reload-page
r reload-page
Neither Emacs nor vi specific
<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
M-r reply-last-input
s search
Minibuffer-specific keys
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-x mini-edit-external
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
C-u mini-kill-whole-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
INTERACTIVE COMMANDS
Follows the documentation for the interactive commands.
These commands can be bound to a key or executed with
execute-extended-command.
Movement commands
backward-char Move point one character
backward.
backward-paragraph Move point one paragraph
backward.
beginning-of-buffer Move point to the beginning of
the buffer.
end-of-buffer Move point to the end of the
buffer.
forward-char Move point one character forward.
forward-paragraph Move point one paragraph forward.
insert-current-candidate Copy the current selection text
as minibuffer input.
move-beginning-of-line Move point at the beginning of
the current (visual) line.
move-end-of-line Move point at the end of the
current (visual) line.
next-button Move point to the next link.
next-completion Select the next completion.
next-heading Move point to the next heading.
next-line Move point to the next (visual)
line, in the same column if
possible.
previous-button Move point to the previous link.
previous-completion Select the previous completion.
previous-heading Move point to the previous
heading.
previous-line Move point to the previous
(visual) line.
Bookmark-related commands
bookmark-page Save a page in the bookmark file.
It preloads the minibuffer with
the current URL.
list-bookmarks Load the bookmarks page.
Client certificate-related commands
client-certificate-info Show the active client
certificate.
unload-certificate Forget the certificate on this
page.
use-certificate Use a certificate for the current
page.
Tab-related commands
tab-close Close the current tab.
tab-close-other Close all tabs but the current
one.
tab-move Move the current tab after the
next one, wrapping around if
needed.
tab-move-to Move the current tab before the
previous one, wrapping around if
needed.
tab-new Open a new tab.
tab-next Focus next tab, wrapping around
eventually.
tab-previous Focus the previous tab, wrapping
around eventually.
tab-select Switch to a tab using the
minibuffer.
tab-undo-close Re-open the most recently closed
tab, if any.
Misc commands
cache-info Show cache stats.
clear-minibuf Clear the echo area.
dec-fill-column Decrement fill-column by two.
execute-extended-command Execute an internal command.
home Go to the home directory. The
home directory is assumed to be
the first path component in the
~username form. If not found,
loads the root directory.
kill-telescope Quit telescope.
inc-fill-column Increment fill-column by two.
link-select Select and visit a link using the
minibuffer.
load-current-url Edit the current URL.
load-url Prompt for an URL. Use the same
heuristic as the URLs given as a
command-line argument, unless the
load-url-use-heuristic option is
unsed, in which case the URL is
resolved using the current one as
base.
next-page Go forward in the page history.
olivetti-mode Toggle olivetti mode (i.e.
horizontal centering of the lines
of the window.)
other-window Select the other window.
previous-page Go backward in the page history.
push-button 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.
push-button-new-tab Follow link at point in a new
tab.
redraw Redraw the screen, useful if some
background program messed up the
display.
reload-page Reload the current page.
reply-last-input Reply the last input request.
root Go to the root directory.
search Search using the preferred search
engine.
scroll-down Scroll down by one visual page.
scroll-line-down Scroll down by one line.
scroll-line-up Scroll up by one line.
scroll-up Scroll up by one visual page.
suspend-telescope Suspend the current telescope
session.
swiper Jump to a line using the
minibuffer.
toc Jump to a heading using the
minibuffer.
toggle-help Toggle side window with help
about available keys and their
associated interactive command.
toggle-pre-wrap Toggle the wrapping of
preformatted blocks.
toggle-styling Toggle the styling of the page.
This remains in effect until
toggled again.
up Go up one level in the path
hierarchy.
write-buffer Save the current buffer to the
disk.
Minibuffer commands
mini-abort Abort the current minibuffer
action.
mini-complete-and-exit Complete the current minibuffer
action.
mini-delete-backward-char
Delete the character before the
point.
mini-delete-char Delete the character after the
point.
mini-edit-external Edit the minibuffer contents with
an editor.
mini-goto-beginning Select the first completion, if
any.
mini-goto-end Select the last completion, if
any.
mini-kill-line Delete from point until the end
of the line.
mini-kill-whole-line Delete the whole line.
mini-next-history-element
Load the previous history
element.
mini-previous-history-element
Load the next history element.
Aliases
The following aliases are available during
execute-extended-command:
open load-url
tabn tab-next
tabnew tab-new
tabp tab-previous
q and wq kill-telescope
w write-buffer
ENVIRONMENT
When telescope is started, it inspects the following
environment variables:
HOME The user's login directory.
NO_COLORS To decide whether to use colors or not. The
content of the variable doesn't matter.
TERM The user's terminal name.
VISUAL, EDITOR
The editor spawned by the mini-edit-external
command. If not set, ed(1) the standard text
editor is used.
XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME
If defined can alter the default location of the
files used.
FILES
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.
~/.config/telescope/certs.conf
URLs to client certificate mappings.
~/.local/share/telescope/pages/about_*.gmi
Overrides for built-in about: pages.
~/.local/share/telescope/bookmarks.gmi
Bookmarks file.
~/.local/share/telescope/certs/
Directory where client certificates (identities)
are stored.
~/.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.
EXAMPLES
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
SEE ALSO
telescope-identity(1) xdg-open(1)
STANDARDS
XDG Base Directory Specification,
https://specifications.freedesktop.org/basedir-spec/latest/.
ACKNOWLEDGEMENTS
The “Trust, but verify (where appropriate)” TOFU scheme was
firstly suggested by thfr:
gemini://thfr.info/gemini/modified-trust-verify.gmi.
AUTHORS
The telescope program was written by Omar Polo
<op@omarpolo.com>.
CAVEATS
telescope assumes a UTF-8 environment and doesn't try to
cope with other encodings. This can cause strange
rendering issues if you're lucky, or possibly weird thing
happening depending on your locale and terminal emulator.
BUGS
There's no UI for out-of-band certificates validation.
Linux 6.1.0-20-amd64 February 23, 2024 Linux 6.1.0-20-amd64