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
-nosplit 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.