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
24 validity.
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
30 about pages.
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
42 direction.
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
62 value.
64 trusted (v) the server fingerprint matches the store one.
66 verified (V) the fingerprint matches and has been verified out-of-
67 band.
69 The trust level of the page is indicated in the modeline with the
70 indicated character.
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
76 verification though.
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)
89 are available.
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-
100 certificates.
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
119 exists.
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:
129 bind map key cmd
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.
136 proxy proto via url
137 Use url as proxy for all URLs with protocol proto. url must be a
138 Gemini URI without path, query and fragment component.
140 set opt = val
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
146 ...) Defaults to 20.
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
150 /tmp.
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.
159 hide-pre-blocks
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
163 per-block.
164 hide-pre-closing-line
165 (integer) If nonzero, hide the closing line of
166 preformatted blocks. Defaults to 0.
167 hide-pre-context
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.
172 Defaults to zero.
173 new-tab-url (string) URL for the new tab page. Defaults to
174 about:new.
175 olivetti-mode (integer) If nonzero, enable olivetti-mode
176 Defaults to 1.
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.
184 style name option
185 Change the styling of the element identified by name. Multiple
186 options may be specified within curly braces. Valid style
187 identifiers are:
188 line the area outside the lines in the
189 body of the page.
190 line.compl the completions.
191 line.compl.current the current completion.
192 text in the *Help* buffer.
193 an ongoing download
194 a completed download
195 informational text in the
196 *Downloads* buffer.
197 line.text text lines.
198 link lines.
199 line.title1..3 headings
200 line.item item lines.
201 line.quote quotes.
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
205 block.
206 download the download pane
207 minibuffer the minibuffer.
208 modeline the modeline.
209 tabline the tabline.
210 the non-focused tabs.
211 tabline.current the focused tab.
213 Valid options are:
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.
225 dim half bright.
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
230 first one given.
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.
242 prefix prfx [cont]
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.
259 <up> Up arrow
260 <down> Down arrow
261 <left> Left arrow
262 <right> Right arrow
263 <prior> Previous page/Page up
264 <next> Next page/Page down
265 <home> Home
266 <end> End
267 <f0> thru <f63> Function keys
268 del or backspace Backspace
269 esc Escape
270 space or spc Space
271 enter or ret Enter
272 tab Tab
273 backtab Depends on the configuration of the terminal
274 emulator; usually shift tab.
276 GNU Emacs-like keys
277 C-p previous-line
278 C-n next-line
279 C-f forward-char
280 C-b backward-char
281 M-{ backward-paragraph
282 M-} forward-paragraph
283 C-a move-beginning-of-line
284 C-e move-end-of-line
285 M-v, M-space scroll-up
286 C-v, space scroll-down
287 M-< beginning-of-buffer
288 M-> end-of-buffer
289 C-x C-c kill-telescope
290 C-g clear-minibuf
291 M-x execute-extended-command
292 C-c { dec-fill-column
293 C-c } inc-fill-column
294 C-c p previous-heading
295 C-c n next-heading
296 > load-url
297 < load-current-url
298 C-x C-f load-url
299 C-x M-f load-current-url
300 C-x o other-window
301 C-x t 0 tab-close
302 C-x t 1 tab-close-other
303 C-x t 2 tab-new
304 C-x t o tab-next
305 C-x t O tab-previous
306 C-x t m tab-move
307 C-x t M tab-move-to
308 B, C-M-b previous-page
309 F, C-M-f next-page
310 <f7> a bookmark-page
311 <f7> <f7> list-bookmarks
312 C-z suspend-telescope
314 vi(1)-like keys
315 k previous-line
316 j next-line
317 l forward-char
318 h backward-char
319 { backward-paragraph
320 } forward-paragraph
321 ^ move-beginning-of-line
322 $ move-end-of-line
323 K scroll-line-up
324 J scroll-line-down
325 g g beginning-of-buffer
326 G end-of-buffer
327 g D tab-close
328 g N tab-new
329 g t tab-next
330 g T tab-previous
331 g M-t tab-move
332 g M-T tab-move-to
333 H previous-page
334 L next-page
335 q kill-telescope
336 ESC clear-minibuf
337 : execute-extended-command
339 CUA-like keys
340 <up> previous-line
341 <down> next-line
342 <right> forward-char
343 <left> backward-char
344 <home> move-beginning-of-line
345 <end> move-end-of-line
346 <prior> scroll-up
347 <next> scroll-down
348 C-w tab-close
349 C-t tab-new
350 M-<prior> tab-previous
351 M-<next> tab-next
352 M-<left> previous-page
353 M-<right> next-page
354 <f5> reload-page
355 r reload-page
357 Neither Emacs nor vi specific
358 <f1> toggle-help
359 enter push-button
360 M-enter push-button-new-tab
361 M-tab previous-button
362 backtab previous-button
363 tab next-button
364 M-t tab-select
365 [ tab-previous
366 ] tab-next
367 M-[ tab-move-to
368 M-] tab-move
369 M-l link-select
370 M-/ swiper
372 Minibuffer-specific keys
373 enter mini-complete-and-exit
374 C-g mini-abort
375 ESC mini-abort
376 C-d mini-delete-char
377 del mini-delete-backward-char
378 backspace mini-delete-backward-char
379 C-h mini-delete-backward-char
380 C-b backward-char
381 C-f forward-char
382 <left> backward-char
383 <right> forward-char
384 C-e move-end-of-line
385 C-a move-beginning-of-line
386 <end> move-end-of-line
387 <home> move-beginning-of-line
388 C-k mini-kill-line
389 M-p mini-previous-history-element
390 M-n mini-next-history-element
391 C-p previous-completion
392 C-n next-completion
393 <up> previous-completion
394 <down> next-completion
395 tab insert-current-candidate
396 M-< mini-goto-beginning
397 M-> mini-goto-end
400 Follows the documentation for the interactive commands. These commands
401 can be bound to a key or executed with execute-extended-command.
403 Movement commands
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
411 input.
412 move-beginning-of-line Move point at the beginning of the current
413 (visual) line.
414 move-end-of-line Move point at the end of the current (visual)
415 line.
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.
431 Tab-related commands
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
441 eventually.
442 tab-select Switch to a tab using the minibuffer.
444 Misc commands
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.
476 Minibuffer commands
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.
490 Aliases
491 The following aliases are available during execute-extended-command:
492 tabn tab-next
493 tabnew tab-new
494 tabp tab-previous
495 q and wq kill-telescope
498 When telescope is started, it inspects the following environment
499 variables:
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.
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
522 Bookmarks file.
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://"
542 proxy https via "gemini://"
544 To load telescope without any configuration
546 telescope -c /dev/null
549 XDG Base Directory Specification,
553 The telescope program was written by Omar Polo <>.
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
559 emulator.
561 BUGS
562 There's no UI for out-of-band certificates validation.
564 OpenBSD 7.0 November 29, 2021 OpenBSD 7.0