1 TELESCOPE(1) General Commands Manual TELESCOPE(1)
4 telescope multi-protocol browser
7 telescope [-ChnSv] [-c config] [URL]
10 telescope is an interactive browser that supports the Finger, Gemini and
11 Gopher protocols. telescope features tabs, a minibuffer, interactive
12 completions, bookmarks and out-of-band TOFU verification.
14 The arguments are as follows:
16 -C, --colors Show all available colors and exit.
18 -c config Specify an alternative configuration file. By default
19 ~/.config/telescope/config is loaded.
21 -h, --help Display version and usage.
23 -n Configtest mode. Only check the configuration file for
26 -S, --safe Safe (or sandbox) mode. Prevent telescope from
27 writing files to the disk and to acquire the lock,
28 allowing to run multiple instances at the same time.
29 telescope still loads the session file and the custom
32 -v, --version Display version.
35 telescope interface is divided into four areas: the tabline, the body,
36 the modeline and the echoarea/minibuffer.
38 The tabline is always at the top of the screen and displays the tabs
39 separated by a vertical line. When there are more tabs than the size of
40 the window allow to display, the characters < or > are shown at the
41 start/end of the tabline to indicate that there are more tabs in that
44 The body occupies the majority of the visible area. It contains the
45 current page and optionally a side window.
47 The modeline is the second to last row of the screen. It shows some
48 information about the page: a spinner when the page is loading, the trust
49 level, the document type, the scroll offset and the URL.
51 The echoarea is usually the last line of the screen. Messages are often
52 showed there, and link addresses too. The echoarea is also used to
53 obtain input from the user. When commands like swiper or link-select are
54 invoked, the minibuffer area grows to show possible completions.
57 telescope aims to use the Trust, but Verify (where appropriate)
58 approach for TOFU (Trust On First Use). The idea is to define three
59 level of verification for a certificate:
61 untrusted (!) the server fingerprint does NOT match the stored
64 trusted (v) the server fingerprint matches the store one.
66 verified (V) the fingerprint matches and has been verified out-of-
69 The trust level of the page is indicated in the modeline with the
72 Most of the time the trusted level is enough, but where is appropriate
73 users should be able to verify out-of-band the certificate.
75 At the moment, there is no built-in support for an out-of-band
79 The following protocols are supported:
81 about: About pages are telescope internal page. See about:about for
82 a list of all these pages.
84 file:// File types know to telescope, such as .gmi, .gemini, .txt,
85 .md, .markdown, .diff or .patch, can be viewed inside the
86 application. Types of local files are detected solely based
87 on the file extension. On some systems, such as OpenBSD, only
88 files inside special directories (like /tmp or ~/Downloads)
91 finger:// Finger URLs are interpreted as follows:
92 the host is determined by the host name portion of the URL
93 if the user portion of the URL is provided, it's
94 interpreted as the user to finger, otherwise the path
95 component will be used
96 thus finger://user@hostname and finger://hostname/user are
97 treated as the same URL.
99 gemini:// Gemini is fully supported, with the exception of client-
102 gopher:// Gopher support is limited to items type 0, 1 and 7. All text
103 is assumed to be encoded in UTF-8 (or ASCII).
105 User-entered URLs, given as argument on the command line or entered with
106 load-url, are intepreted with a simple heuristic:
107 if it's a proper absolute URL then use it as-is,
108 if it starts with ./ or / assume it's a file:// URL,
109 otherwise assume it's a Gemini URL.
112 During the startup, telescope reads the configuration file at
113 ~/.config/telescope/config or ~/.telescope/config.
115 It's possible to load a custom configuration file using the -c flag.
117 telescope will also load a file called config-TERM, where TERM is the
118 name of the terminal type (i.e. the TERM environment variable), if it
121 The format of the configuration file is fairly flexible. The current
122 line can be extended over multiple ones using a backslash (\).
123 Comments can be put anywhere in the file using a hash mark (#), and
124 extend to the end of the current line, but backslashes can't be used to
125 extend comments over multiple lines.
127 The following constructs are available:
130 Bind key to the function cmd in the keymap map. Valid values for
131 map are global-map (i.e. when the user is viewing a page) and
132 minibuffer-map (i.e. when the minibuffer has the focus.) key
133 follows the same syntax described in DEFAULT KEY BINDINGS and all
134 the possible functions are listed in INTERACTIVE COMMANDS.
137 Use url as proxy for all URLs with protocol proto. url must be a
138 Gemini URI without path, query and fragment component.
141 Set the option opt to the value val. Valid options are:
143 autosave (integer) If greater than zero, save the session
144 after the specified amount of seconds after some
145 events happens (new or closed tabs, visited a link
147 dont-wrap-pre (integer) If nonzero, don't wrap preformatted
148 blocks. Defaults to 0.
149 download-path (string) The default download path. Defaults to
151 emojify-link (integer) If nonzero, when the text of a link
152 starts with an emoji followed by a space, use that
153 emoji as line prefix. Defaults to 1.
154 enable-colors (integer) If nonzero, enable colours. Defaults to
155 0 if NO_COLORS is set, 1 otherwise.
156 fill-column (integer) If greater than zero, lines of text will
157 be formatted in a way that don't exceed the given
158 number of columns. Defaults to 80.
160 (integer) If nonzero, hide by default the body of
161 the preformatted blocks. Defaults to zero.
162 push-button can be used to toggle the visibility
164 hide-pre-closing-line
165 (integer) If nonzero, hide the closing line of
166 preformatted blocks. Defaults to 0.
168 (integer) If nonzero, hide the start and end line
169 of the preformatted blocks. If both hide-pre-
170 context and hide-pre-blocks are nonzero,
171 preformatted blocks are irremediably hidden.
173 new-tab-url (string) URL for the new tab page. Defaults to
175 olivetti-mode (integer) If nonzero, enable olivetti-mode
177 set-title (integer) If nonzero, set the terminal title to
178 the page title. Defaults to 1.
179 tab-bar-show (integer) If tab-bar-show is -1 hide the tab bar
180 permanently, if 0 show it unconditionally. If
181 it's 1, show the bar only when there is more than
182 one tab. Defaults to 1.
185 Change the styling of the element identified by name. Multiple
186 options may be specified within curly braces. Valid style
188 line the area outside the lines in the
190 line.compl the completions.
191 line.compl.current the current completion.
192 line.help text in the *Help* buffer.
193 line.download.ongoing an ongoing download
194 line.download.done a completed download
195 line.download.info informational text in the
197 line.text text lines.
198 line.link link lines.
199 line.title1..3 headings
200 line.item item lines.
202 line.pre.start the heading of a preformatted block.
203 line.pre the content of a preformatted block.
204 line.pre.end the closing line of a preformatted
206 download the download pane
207 minibuffer the minibuffer.
208 modeline the modeline.
210 tabline.tab the non-focused tabs.
211 tabline.current the focused tab.
215 attr prefix [line [trail]]
216 Sets the text attributes. If only one value is given,
217 line and trail default to that; if two values are given
218 then trail defaults to prefix. Each attribute is a
219 comma-separated list of keywords:
220 normal no attributes.
221 standout best highlighting mode for the terminal.
222 underline underlines the text.
223 reverse reverses background/foreground colors.
224 blink makes the text blinking.
226 bold extra bright or bold.
228 Only the style identifiers with the line. prefix accept
229 up to three attributes. The other will only use the
232 bg prefix [line [trail]]
233 Sets the background color. Follows the same behaviour as
234 attr regarding the optional parameters. The colour is
235 one of black, red, green, yellow, blue, magenta, cyan and
236 white; colour0 to colour255 (or color0 to color255) from
237 the 256-colour set; default for the default colour.
239 fg prefix [line [trail]]
240 Sets the foreground color. It behaves just like bg.
243 Sets the prefix for the current line type to prfx and
244 cont as the prefix for the continuation lines (i.e. when
245 a long line gets wrapped.) If cont is not given its value
246 will be the same of prfx.
249 The default key bindings are very similar to GNU Emacs, but care has been
250 taken to include also bindings familiar for vi(1) and CUA users. In
251 the following examples, C-x means Control-x, M-x means Meta-x, where the
252 Meta key may be either a special key on the keyboard or the ALT key;
253 otherwise ESC followed by the key X works as well, and C-M-x means to
254 press the key X together with both Control and Meta.
256 Keys are usually a single character, like p or n, but some special
257 keys are accepted as well.
263 <prior> Previous page/Page up
264 <next> Next page/Page down
267 <f0> thru <f63> Function keys
268 del or backspace Backspace
273 backtab Depends on the configuration of the terminal
274 emulator; usually shift tab.
281 M-{ backward-paragraph
282 M-} forward-paragraph
283 C-a move-beginning-of-line
285 M-v, M-space scroll-up
286 C-v, space scroll-down
287 M-< beginning-of-buffer
289 C-x C-c kill-telescope
291 M-x execute-extended-command
292 C-c { dec-fill-column
293 C-c } inc-fill-column
294 C-c p previous-heading
299 C-x M-f load-current-url
302 C-x t 1 tab-close-other
308 B, C-M-b previous-page
311 <f7> <f7> list-bookmarks
312 C-z suspend-telescope
321 ^ move-beginning-of-line
325 g g beginning-of-buffer
337 : execute-extended-command
344 <home> move-beginning-of-line
345 <end> move-end-of-line
350 M-<prior> tab-previous
352 M-<left> previous-page
357 Neither Emacs nor vi specific
360 M-enter push-button-new-tab
361 M-tab previous-button
362 backtab previous-button
372 Minibuffer-specific keys
373 enter mini-complete-and-exit
377 del mini-delete-backward-char
378 backspace mini-delete-backward-char
379 C-h mini-delete-backward-char
385 C-a move-beginning-of-line
386 <end> move-end-of-line
387 <home> move-beginning-of-line
389 M-p mini-previous-history-element
390 M-n mini-next-history-element
391 C-p previous-completion
393 <up> previous-completion
394 <down> next-completion
395 tab insert-current-candidate
396 M-< mini-goto-beginning
400 Follows the documentation for the interactive commands. These commands
401 can be bound to a key or executed with execute-extended-command.
404 backward-char Move point one character backward.
405 backward-paragraph Move point one paragraph backward.
406 beginning-of-buffer Move point to the beginning of the buffer.
407 end-of-buffer Move point to the end of the buffer.
408 forward-char Move point one character forward.
409 forward-paragraph Move point one paragraph forward.
410 insert-current-candidate Copy the current selection text as minibuffer
412 move-beginning-of-line Move point at the beginning of the current
414 move-end-of-line Move point at the end of the current (visual)
416 next-button Move point to the next link.
417 next-completion Select the next completion.
418 next-heading Move point to the next heading.
419 next-line Move point to the next (visual) line, in the
420 same column if possible.
421 previous-button Move point to the previous link.
422 previous-completion Select the previous completion.
423 previous-heading Move point to the previous heading.
424 previous-line Move point to the previous (visual) line.
426 Bookmark-related commands
427 bookmark-page Save a page in the bookmark file. It preloads
428 the minibuffer with the current URL.
429 list-bookmarks Load the bookmarks page.
432 tab-close Close the current tab.
433 tab-close-other Close all tabs but the current one.
434 tab-move Move the current tab after the next one,
435 wrapping around if needed.
436 tab-move-to Move the current tab before the previous one,
437 wrapping around if needed.
438 tab-new Open a new tab.
439 tab-next Focus next tab, wrapping around eventually.
440 tab-previous Focus the previous tab, wrapping around
442 tab-select Switch to a tab using the minibuffer.
445 clear-minibuf Clear the echo area.
446 dec-fill-column Decrement fill-column by two.
447 execute-extended-command Execute an internal command.
448 kill-telescope Quit telescope.
449 inc-fill-column Increment fill-column by two.
450 link-select Select and visit a link using the minibuffer.
451 load-current-url Edit the current URL.
452 load-url Prompt for an URL.
453 next-page Go forward in the page history.
454 olivetti-mode Toggle olivetti mode (i.e. horizontal centering
455 of the lines of the window.)
456 other-window Select the other window.
457 previous-page Go backward in the page history.
458 push-button Follow link at point, or toggle the visibility
459 of the following preformatted block if called
460 when the cursor is on the heading of the block.
461 push-button-new-tab Follow link at point in a new tab.
462 redraw Redraw the screen, useful if some background
463 program messed up the display.
464 reload-page Reload the current page.
465 scroll-down Scroll down by one visual page.
466 scroll-line-down Scroll down by one line.
467 scroll-line-up Scroll up by one line.
468 scroll-up Scroll up by one visual page.
469 suspend-telescope Suspend the current telescope session.
470 swiper Jump to a line using the minibuffer.
471 toc Jump to a heading using the minibuffer.
472 toggle-help Toggle side window with help about available
473 keys and their associated interactive command.
474 toggle-pre-wrap Toggle the wrapping of preformatted blocks.
477 mini-abort Abort the current minibuffer action.
478 mini-complete-and-exit Complete the current minibuffer action.
479 mini-delete-backward-char
480 Delete the character before the point.
481 mini-delete-char Delete the character after the point.
482 mini-goto-beginning Select the first completion, if any.
483 mini-goto-end Select the last completion, if any.
484 mini-kill-line Delete from point until the end of the line.
485 mini-next-history-element
486 Load the previous history element.
487 mini-previous-history-element
488 Load the next history element.
491 The following aliases are available during execute-extended-command:
495 q and wq kill-telescope
498 When telescope is started, it inspects the following environment
501 HOME The user's login directory.
503 NO_COLORS To decide whether to use colors or not. The content of the
504 variable doesn't matter.
506 TERM The user's terminal name.
508 XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME
509 If defined can alter the default location of the files used.
512 By default telescope follows the XDG Base Directory Specification.
513 However, if ~/.telescope exists, XDG is ignored and all the files are
514 stored inside it. The usage of XDG_CACHE_HOME, XDG_CONFIG_HOME and
515 XDG_DATA_HOME can further alter the location of these files.
517 ~/.config/telescope/config
518 Default configuration file.
519 ~/.local/share/telescope/pages/about_*.gmi
520 Overrides for built-in about: pages.
521 ~/.local/share/telescope/bookmarks.gmi
523 ~/.local/share/telescope/known_hosts
524 Hash of the certificates for all the known hosts. Each line
525 contains three fields: hostname with optional port number, hash
526 of the certificate and a numeric flag.
527 ~/.cache/telescope/lock
528 Lock file used to prevent multiple instance of telescope from
529 running at the same time.
530 ~/.cache/telescope/session
531 The list of tabs from the last session. Every line identifies a
532 tab and contains three space-separated fields: the full URL, a
533 comma-separated list of attributes and the cached title. Is
534 written by kill-telescope and loaded during startup.
537 It's possible to browse the small web (i.e. simple websites) by using
538 programs like the duckling-proxy by defining a proxy in
539 ~/.config/telescope/config:
541 proxy http via "gemini://127.0.0.1:1965"
542 proxy https via "gemini://127.0.0.1:1965"
544 To load telescope without any configuration
546 telescope -c /dev/null
549 XDG Base Directory Specification,
550 https://specifications.freedesktop.org/basedir-spec/latest/.
553 The telescope program was written by Omar Polo <op@omarpolo.com>.
556 telescope assumes a UTF-8 environment and doesn't do anything to cope
557 with other encodings. This can cause weird rendering issues if you're
558 lucky, or possibly worst things depending on your locale and terminal
562 There's no UI for out-of-band certificates validation.
564 OpenBSD 7.0 November 29, 2021 OpenBSD 7.0
