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, --colours Show all available colors and exit. This option can also
19 -c config Specify an alternative configuration file. By default
20 ~/.config/telescope/config is loaded.
22 -h, --help Display version, usage and exit.
24 -n Configtest mode. Only check the configuration file for
27 -S, --safe Safe (or sandbox) mode. Prevent telescope from
28 writing files to the disk and to acquire the lock,
29 allowing to run multiple instances at the same time.
30 telescope still loads the session file and the custom
33 -v, --version Display version and exit.
36 telescope interface is divided into four areas: the tabline, the body,
37 the modeline and the echoarea/minibuffer.
39 The tabline is always at the top of the screen and displays the tabs
40 separated by a vertical line. When there are more tabs than the size of
41 the window allow to display, the characters < or > are shown at the
42 start/end of the tabline to indicate that there are more tabs in that
45 The body occupies the majority of the visible area. It contains the
46 current page and optionally a side window.
48 The modeline is the second to last row of the screen. It shows some
49 information about the page: a spinner when the page is loading, the trust
50 level, the document type, the scroll offset and the URL.
52 The echoarea is usually the last line of the screen. Messages are often
53 showed there, and link addresses too. The echoarea is also used to
54 obtain input from the user. When commands like swiper or link-select are
55 invoked, the minibuffer area grows to show possible completions.
58 telescope aims to use the Trust, but Verify (where appropriate)
59 approach for TOFU (Trust On First Use). The idea is to define three
60 level of verification for a certificate:
62 untrusted (!) the server fingerprint does NOT match the stored
65 trusted (v) the server fingerprint matches the store one.
67 verified (V) the fingerprint matches and has been verified out-of-
70 The trust level of the page is indicated in the modeline with the
73 Most of the time the trusted level is enough, but where is appropriate
74 users should be able to verify out-of-band the certificate.
76 At the moment, there is no built-in support for an out-of-band
80 The following protocols are supported:
82 about: About pages are telescope internal page. See about:about for
83 a list of all these pages.
85 file:// File types know to telescope, such as .gmi, .gemini, .txt,
86 .md, .markdown, .diff or .patch, can be viewed inside the
87 application. Types of local files are detected solely based
88 on the file extension. On some systems, such as OpenBSD, only
89 files inside special directories (like /tmp or ~/Downloads)
92 finger:// Finger URLs are interpreted as follows:
93 the host is determined by the host name portion of the URL
94 if the user portion of the URL is provided, it's
95 interpreted as the user to finger, otherwise the path
96 component will be used
97 thus finger://user@hostname and finger://hostname/user are
98 treated as the same URL.
100 gemini:// Gemini is fully supported, with the exception of client-
103 gopher:// Gopher support is limited to items type 0, 1 and 7. All text
104 is assumed to be encoded in UTF-8 (or ASCII).
106 User-entered URLs, given as argument on the command line or entered with
107 load-url, are intepreted with a simple heuristic:
108 if it's a proper absolute URL then use it as-is,
109 if it starts with ./ or / assume it's a file:// URL,
110 otherwise assume it's a Gemini URL.
113 During the startup, telescope reads the configuration file at
114 ~/.config/telescope/config or ~/.telescope/config.
116 It's possible to load a custom configuration file using the -c flag.
118 telescope will also load a file called config-TERM, where TERM is the
119 name of the terminal type (i.e. the TERM environment variable), if it
122 The format of the configuration file is fairly flexible. The current
123 line can be extended over multiple ones using a backslash (\).
124 Comments can be put anywhere in the file using a hash mark (#), and
125 extend to the end of the current line, but backslashes can't be used to
126 extend comments over multiple lines.
128 The following constructs are available:
131 Bind key to the function cmd in the keymap map. Valid values for
132 map are global-map (i.e. when the user is viewing a page) and
133 minibuffer-map (i.e. when the minibuffer has the focus.) key
134 follows the same syntax described in DEFAULT KEY BINDINGS and all
135 the possible functions are listed in INTERACTIVE COMMANDS.
138 Use url as proxy for all URLs with protocol proto. url must be a
139 Gemini URI without path, query and fragment component.
142 Set the option opt to the value val. Valid options are:
144 autosave (integer) If greater than zero, save the session
145 after the specified amount of seconds after some
146 events happens (new or closed tabs, visited a link
148 dont-wrap-pre (integer) If nonzero, don't wrap preformatted
149 blocks. Defaults to 0.
150 download-path (string) The default download path. Defaults to
152 emojify-link (integer) If nonzero, when the text of a link
153 starts with an emoji followed by a space, use that
154 emoji as line prefix. Defaults to 1.
155 enable-colors (integer) If nonzero, enable colours. Defaults to
156 0 if NO_COLORS is set, 1 otherwise.
157 fill-column (integer) If greater than zero, lines of text will
158 be formatted in a way that don't exceed the given
159 number of columns. Defaults to 80.
161 (integer) If nonzero, the fringe doesn't obey to
162 olivetti-mode. Defaults to 1.
164 (integer) If nonzero, hide by default the body of
165 the preformatted blocks. Defaults to zero.
166 push-button can be used to toggle the visibility
168 hide-pre-closing-line
169 (integer) If nonzero, hide the closing line of
170 preformatted blocks. Defaults to 0.
172 (integer) If nonzero, hide the start and end line
173 of the preformatted blocks. If both hide-pre-
174 context and hide-pre-blocks are nonzero,
175 preformatted blocks are irremediably hidden.
177 new-tab-url (string) URL for the new tab page. Defaults to
180 (integer) The maximum number of closed tabs to
181 keep track of, defaults to 10. Must be a positive
182 number; if zero, don't save closed tabs at all.
183 olivetti-mode (integer) If nonzero, enable olivetti-mode
185 tab-bar-show (integer) If tab-bar-show is -1 hide the tab bar
186 permanently, if 0 show it unconditionally. If
187 it's 1, show the bar only when there is more than
188 one tab. Defaults to 1.
189 update-title (integer) If nonzero, set the terminal title to
190 the page title. Defaults to 1.
193 Change the styling of the element identified by name. Multiple
194 options may be specified within curly braces. Valid style
196 line the area outside the lines in the
198 line.compl the completions.
199 line.compl.current the current completion.
200 line.help text in the *Help* buffer.
201 line.download.ongoing an ongoing download
202 line.download.done a completed download
203 line.download.info informational text in the
205 line.fringe (virtual) lines draw after the end
207 line.text text lines.
208 line.link link lines.
209 line.title1..3 headings
210 line.item item lines.
212 line.pre.start the heading of a preformatted block.
213 line.pre the content of a preformatted block.
214 line.pre.end the closing line of a preformatted
216 download the download pane
217 minibuffer the minibuffer.
218 modeline the modeline.
220 tabline.tab the non-focused tabs.
221 tabline.current the focused tab.
225 attr prefix [line [trail]]
226 Sets the text attributes. If only one value is given,
227 line and trail default to that; if two values are given
228 then trail defaults to prefix. Each attribute is a
229 comma-separated list of keywords:
230 normal no attributes.
231 standout best highlighting mode for the terminal.
232 underline underlines the text.
233 reverse reverses background/foreground colors.
234 blink makes the text blinking.
236 bold extra bright or bold.
238 Only the style identifiers with the line. prefix accept
239 up to three attributes. The other will only use the
242 bg prefix [line [trail]]
243 Sets the background color. Follows the same behaviour as
244 attr regarding the optional parameters. The colour is
245 one of black, red, green, yellow, blue, magenta, cyan and
246 white; colour0 to colour255 (or color0 to color255) from
247 the 256-colour set; default for the default colour.
249 fg prefix [line [trail]]
250 Sets the foreground color. It behaves just like bg.
253 Sets the prefix for the current line type to prfx and
254 cont as the prefix for the continuation lines (i.e. when
255 a long line gets wrapped.) If cont is not given its value
256 will be the same of prfx.
259 The default key bindings are very similar to GNU Emacs, but care has been
260 taken to include also bindings familiar for vi(1) and CUA users. In
261 the following examples, C-x means Control-x, M-x means Meta-x, where the
262 Meta key may be either a special key on the keyboard or the ALT key;
263 otherwise ESC followed by the key X works as well, and C-M-x means to
264 press the key X together with both Control and Meta.
266 Keys are usually a single character, like p or n, but some special
267 keys are accepted as well.
273 <prior> Previous page/Page up
274 <next> Next page/Page down
277 <f0> thru <f63> Function keys
278 del or backspace Backspace
283 backtab Depends on the configuration of the terminal
284 emulator; usually shift tab.
291 M-{ backward-paragraph
292 M-} forward-paragraph
293 C-a move-beginning-of-line
295 M-v, M-space scroll-up
296 C-v, space scroll-down
297 M-< beginning-of-buffer
299 C-x C-c kill-telescope
301 M-x execute-extended-command
302 C-c { dec-fill-column
303 C-c } inc-fill-column
304 C-c p previous-heading
309 C-x M-f load-current-url
312 C-x t 1 tab-close-other
318 B, C-M-b previous-page
321 <f7> <f7> list-bookmarks
322 C-z suspend-telescope
331 ^ move-beginning-of-line
335 g g beginning-of-buffer
348 : execute-extended-command
355 <home> move-beginning-of-line
356 <end> move-end-of-line
361 M-<prior> tab-previous
364 M-<left> previous-page
369 Neither Emacs nor vi specific
372 M-enter push-button-new-tab
373 M-tab previous-button
374 backtab previous-button
384 Minibuffer-specific keys
385 enter mini-complete-and-exit
389 del mini-delete-backward-char
390 backspace mini-delete-backward-char
391 C-h mini-delete-backward-char
397 C-a move-beginning-of-line
398 <end> move-end-of-line
399 <home> move-beginning-of-line
401 M-p mini-previous-history-element
402 M-n mini-next-history-element
403 C-p previous-completion
405 <up> previous-completion
406 <down> next-completion
407 tab insert-current-candidate
408 M-< mini-goto-beginning
412 Follows the documentation for the interactive commands. These commands
413 can be bound to a key or executed with execute-extended-command.
416 backward-char Move point one character backward.
417 backward-paragraph Move point one paragraph backward.
418 beginning-of-buffer Move point to the beginning of the buffer.
419 end-of-buffer Move point to the end of the buffer.
420 forward-char Move point one character forward.
421 forward-paragraph Move point one paragraph forward.
422 insert-current-candidate Copy the current selection text as minibuffer
424 move-beginning-of-line Move point at the beginning of the current
426 move-end-of-line Move point at the end of the current (visual)
428 next-button Move point to the next link.
429 next-completion Select the next completion.
430 next-heading Move point to the next heading.
431 next-line Move point to the next (visual) line, in the
432 same column if possible.
433 previous-button Move point to the previous link.
434 previous-completion Select the previous completion.
435 previous-heading Move point to the previous heading.
436 previous-line Move point to the previous (visual) line.
438 Bookmark-related commands
439 bookmark-page Save a page in the bookmark file. It preloads
440 the minibuffer with the current URL.
441 list-bookmarks Load the bookmarks page.
444 tab-close Close the current tab.
445 tab-close-other Close all tabs but the current one.
446 tab-move Move the current tab after the next one,
447 wrapping around if needed.
448 tab-move-to Move the current tab before the previous one,
449 wrapping around if needed.
450 tab-new Open a new tab.
451 tab-next Focus next tab, wrapping around eventually.
452 tab-previous Focus the previous tab, wrapping around
454 tab-select Switch to a tab using the minibuffer.
455 tab-undo-close Re-open the most recently closed tab, if any.
458 cache-info Show cache stats.
459 clear-minibuf Clear the echo area.
460 dec-fill-column Decrement fill-column by two.
461 execute-extended-command Execute an internal command.
462 kill-telescope Quit telescope.
463 inc-fill-column Increment fill-column by two.
464 link-select Select and visit a link using the minibuffer.
465 load-current-url Edit the current URL.
466 load-url Prompt for an URL.
467 next-page Go forward in the page history.
468 olivetti-mode Toggle olivetti mode (i.e. horizontal centering
469 of the lines of the window.)
470 other-window Select the other window.
471 previous-page Go backward in the page history.
472 push-button Follow link at point, or toggle the visibility
473 of the following preformatted block if called
474 when the cursor is on the heading of the block.
475 push-button-new-tab Follow link at point in a new tab.
476 redraw Redraw the screen, useful if some background
477 program messed up the display.
478 reload-page Reload the current page.
479 scroll-down Scroll down by one visual page.
480 scroll-line-down Scroll down by one line.
481 scroll-line-up Scroll up by one line.
482 scroll-up Scroll up by one visual page.
483 suspend-telescope Suspend the current telescope session.
484 swiper Jump to a line using the minibuffer.
485 toc Jump to a heading using the minibuffer.
486 toggle-help Toggle side window with help about available
487 keys and their associated interactive command.
488 toggle-pre-wrap Toggle the wrapping of preformatted blocks.
491 mini-abort Abort the current minibuffer action.
492 mini-complete-and-exit Complete the current minibuffer action.
493 mini-delete-backward-char
494 Delete the character before the point.
495 mini-delete-char Delete the character after the point.
496 mini-goto-beginning Select the first completion, if any.
497 mini-goto-end Select the last completion, if any.
498 mini-kill-line Delete from point until the end of the line.
499 mini-next-history-element
500 Load the previous history element.
501 mini-previous-history-element
502 Load the next history element.
505 The following aliases are available during execute-extended-command:
509 q and wq kill-telescope
512 When telescope is started, it inspects the following environment
515 HOME The user's login directory.
517 NO_COLORS To decide whether to use colors or not. The content of the
518 variable doesn't matter.
520 TERM The user's terminal name.
522 XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME
523 If defined can alter the default location of the files used.
526 By default telescope follows the XDG Base Directory Specification.
527 However, if ~/.telescope exists, XDG is ignored and all the files are
528 stored inside it. The usage of XDG_CACHE_HOME, XDG_CONFIG_HOME and
529 XDG_DATA_HOME can further alter the location of these files.
531 ~/.config/telescope/config
532 Default configuration file.
533 ~/.local/share/telescope/pages/about_*.gmi
534 Overrides for built-in about: pages.
535 ~/.local/share/telescope/bookmarks.gmi
537 ~/.local/share/telescope/known_hosts
538 Hash of the certificates for all the known hosts. Each line
539 contains three fields: hostname with optional port number, hash
540 of the certificate and a numeric flag.
541 ~/.cache/telescope/lock
542 Lock file used to prevent multiple instance of telescope from
543 running at the same time.
544 ~/.cache/telescope/session
545 The list of tabs from the last session.
548 It's possible to browse the small web (i.e. simple websites) by using
549 programs like the duckling-proxy by defining a proxy in
550 ~/.config/telescope/config:
552 proxy http via "gemini://127.0.0.1:1965"
553 proxy https via "gemini://127.0.0.1:1965"
555 To load telescope without any configuration
557 telescope -c /dev/null
560 XDG Base Directory Specification,
561 https://specifications.freedesktop.org/basedir-spec/latest/.
564 The Trust, but verify (where appropriate) TOFU scheme was firstly
565 suggested by thfr: gemini://thfr.info/gemini/modified-trust-verify.gmi.
568 The telescope program was written by Omar Polo <op@omarpolo.com>.
571 telescope assumes a UTF-8 environment and doesn't try to cope with other
572 encodings. This can cause strange rendering issues if you're lucky, or
573 possibly weird thing happening depending on your locale and terminal
576 The algorithm used for text-wrapping is naive and doesn't really work for
577 languages that make heavily use of glyphs composed by multiple UNICODE
581 There's no UI for out-of-band certificates validation.
583 OpenBSD 7.0 January 5, 2022 OpenBSD 7.0
