1 TELESCOPE(1) General Commands Manual TELESCOPE(1)
4 telescope multi-protocol browser
7 telescope [-Chnv] [-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 $HOME/.telescope/config is loaded.
21 -h, --help Display version and usage.
23 -n Configtest mode. Only check the configuration file for
26 -v, --version Display version.
29 telescope interface is divided into four areas: the tabline, the body,
30 the modeline and the echoarea/minibuffer.
32 The tabline is always at the top of the screen and displays the tabs
33 separated by a vertical line. When there are more tabs than the size of
34 the window allow to display, the characters < or > are shown at the
35 start/end of the tabline to indicate that there are more tabs in that
38 The body occupies the majority of the visible area. It contains the
39 current page and optionally a side window.
41 The modeline is the second to last row of the screen. It shows some
42 information about the page: a spinner when the page is loading, the trust
43 level, the document type, the scroll offset and the URL.
45 The echoarea is usually the last line of the screen. Messages are often
46 showed there, and link addresses too. The echoarea is also used to
47 obtain input from the user. When commands like swiper or link-select are
48 invoked, the minibuffer area grows to show possible completions.
51 telescope aims to use the Trust, but Verify (where appropriate)
52 approach for TOFU (Trust On First Use). The idea is to define three
53 level of verification for a certificate:
55 untrusted (!) the server fingerprint does NOT match the stored
58 trusted (v) the server fingerprint matches the store one.
60 verified (V) the fingerprint matches and has been verified out-of-
63 The trust level of the page is indicated in the modeline with the
66 Most of the time the trusted level is enough, but where is appropriate
67 users should be able to verify out-of-band the certificate.
69 At the moment, there is no built-in support for an out-of-band
73 The following protocols are supported:
75 about: About pages are telescope internal page. See about:about for
76 a list of all these pages.
78 file:// File types know to telescope, such as .gmi, .gemini, .txt,
79 .md, .markdown, .diff or .patch, can be viewed inside the
80 application. Types of local files are detected solely based
81 on the file extension. On some systems, such as OpenBSD, only
82 files inside special directories (like /tmp or ~/Downloads)
85 finger:// Finger URLs are interpreted as follows:
86 the host is determined by the host name portion of the URL
87 if the user portion of the URL is provided, it's
88 interpreted as the user to finger, otherwise the path
89 component will be used
90 thus finger://user@hostname and finger://hostname/user are
91 treated as the same URL.
93 gemini:// Gemini is fully supported, with the exception of client-
96 gopher:// Gopher support is limited to items type 0, 1 and 7. All text
97 is assumed to be encoded in UTF-8 (or ASCII).
99 User-entered URLs, given as argument on the command line or entered with
100 load-url, are intepreted with a simple heuristic:
101 if it's a proper absolute URL then use it as-is,
102 if it starts with ./ or / assume it's a file:// URL,
103 otherwise assume it's a Gemini URL.
106 The default key bindings are very similar to GNU Emacs, but care has been
107 taken to include also bindings familiar for vi(1) and CUA users. In
108 the following examples, C-x means Control-x, M-x means Meta-x, where the
109 Meta key may be either a special key on the keyboard or the ALT key;
110 otherwise ESC followed by the key X works as well, and C-M-x means to
111 press the key X together with both Control and Meta.
113 Keys are usually a single character, like p or n, but some special
114 keys are accepted as well.
120 <prior> Previous page/Page up
121 <next> Next page/Page down
124 <f0> thru <f63> Function keys
125 del or backspace Backspace
130 backtab Depends on the configuration of the terminal
131 emulator; usually shift tab.
138 M-{ backward-paragraph
139 M-} forward-paragraph
140 C-a move-beginning-of-line
142 M-v, M-space scroll-up
143 C-v, space scroll-down
144 M-< beginning-of-buffer
146 C-x C-c kill-telescope
148 M-x execute-extended-command
149 C-c { dec-fill-column
150 C-c } inc-fill-column
151 C-c p previous-heading
156 C-x M-f load-current-url
159 C-x t 1 tab-close-other
165 B, C-M-b previous-page
168 <f7> <f7> list-bookmarks
169 C-z suspend-telescope
178 ^ move-beginning-of-line
182 g g beginning-of-buffer
194 : execute-extended-command
201 <home> move-beginning-of-line
202 <end> move-end-of-line
207 M-<prior> tab-previous
209 M-<left> previous-page
214 Neither Emacs nor vi specific
217 M-enter push-button-new-tab
218 M-tab previous-button
219 backtab previous-button
229 Minibuffer-specific keys
230 enter mini-complete-and-exit
234 del mini-delete-backward-char
235 backspace mini-delete-backward-char
236 C-h mini-delete-backward-char
242 C-a move-beginning-of-line
243 <end> move-end-of-line
244 <home> move-beginning-of-line
246 M-p mini-previous-history-element
247 M-n mini-next-history-element
248 C-p previous-completion
250 <up> previous-completion
251 <down> next-completion
252 tab insert-current-candidate
253 M-< mini-goto-beginning
257 Follows the documentation for the interactive commands. These commands
258 can be bound to a key or executed with execute-extended-command.
261 backward-char Move point one character backward.
262 backward-paragraph Move point one paragraph backward.
263 beginning-of-buffer Move point to the beginning of the buffer.
264 end-of-buffer Move point to the end of the buffer.
265 forward-char Move point one character forward.
266 forward-paragraph Move point one paragraph forward.
267 insert-current-candidate Copy the current selection text as minibuffer
269 move-beginning-of-line Move point at the beginning of the current
271 move-end-of-line Move point at the end of the current (visual)
273 next-button Move point to the next link.
274 next-completion Select the next completion.
275 next-heading Move point to the next heading.
276 next-line Move point to the next (visual) line, in the
277 same column if possible.
278 previous-button Move point to the previous link.
279 previous-completion Select the previous completion.
280 previous-heading Move point to the previous heading.
281 previous-line Move point to the previous (visual) line.
283 Bookmark-related commands
284 bookmark-page Save a page in the bookmark file. It preloads
285 the minibuffer with the current URL.
286 list-bookmarks Load the bookmarks page.
289 tab-close Close the current tab.
290 tab-close-other Close all tabs but the current one.
291 tab-move Move the current tab after the next one,
292 wrapping around if needed.
293 tab-move-to Move the current tab before the previous one,
294 wrapping around if needed.
295 tab-new Open a new tab.
296 tab-next Focus next tab, wrapping around eventually.
297 tab-previous Focus the previous tab, wrapping around
299 tab-select Switch to a tab using the minibuffer.
302 clear-minibuf Clear the echo area.
303 dec-fill-column Decrement fill-column by two.
304 execute-extended-command Execute an internal command.
305 kill-telescope Quit telescope.
306 inc-fill-column Increment fill-column by two.
307 link-select Select and visit a link using the minibuffer.
308 load-current-url Edit the current URL.
309 load-url Prompt for an URL.
310 next-page Go forward in the page history.
311 olivetti-mode Toggle olivetti mode (i.e. horizontal centering
312 of the lines of the window.)
313 other-window Select the other window.
314 previous-page Go backward in the page history.
315 push-button Follow link at point, or toggle the visibility
316 of the following preformatted block if called
317 when the cursor is on the heading of the block.
318 push-button-new-tab Follow link at point in a new tab.
319 redraw Redraw the screen, useful if some background
320 program messed up the display.
321 reload-page Reload the current page.
322 scroll-down Scroll down by one visual page.
323 scroll-line-down Scroll down by one line.
324 scroll-line-up Scroll up by one line.
325 scroll-up Scroll up by one visual page.
326 suspend-telescope Suspend the current telescope session.
327 swiper Jump to a line using the minibuffer.
328 toc Jump to a heading using the minibuffer.
329 toggle-help Toggle side window with help about available
330 keys and their associated interactive command.
331 toggle-pre-wrap Toggle the wrapping of preformatted blocks.
334 mini-abort Abort the current minibuffer action.
335 mini-complete-and-exit Complete the current minibuffer action.
336 mini-delete-backward-char
337 Delete the character before the point.
338 mini-delete-char Delete the character after the point.
339 mini-goto-beginning Select the first completion, if any.
340 mini-goto-end Select the last completion, if any.
341 mini-kill-line Delete from point until the end of the line.
342 mini-next-history-element
343 Load the previous history element.
344 mini-previous-history-element
345 Load the next history element.
348 The following aliases are available during execute-extended-command:
352 q and wq kill-telescope
355 During the startup, telescope reads the configuration file at
356 ~/.telescope/config or the one given with the -c flag.
358 telescope will also load a file called config-TERM, where TERM is the
359 name of the terminal type (i.e. the TERM environment variable), if it
362 The format of the configuration file is fairly flexible. The current
363 line can be extended over multiple ones using a backslash (\).
364 Comments can be put anywhere in the file using a hash mark (#), and
365 extend to the end of the current line, but backslashes can't be used to
366 extend comments over multiple lines.
368 The following constructs are available:
371 Bind key to the function cmd in the keymap map. Valid values for
372 map are global-map (i.e. when the user is viewing a page) and
373 minibuffer-map (i.e. when the minibuffer has the focus.) key
374 follows the same syntax described in DEFAULT KEY BINDINGS and all
375 the possible functions are listed in INTERACTIVE COMMANDS.
378 Use url as proxy for all URLs with protocol proto. url must be a
379 Gemini URI without path, query and fragment component.
382 Set the option opt to the value val. Valid options are:
384 autosave (integer) If greater than zero, save the session
385 after the specified amount of seconds after some
386 events happens (new or closed tabs, visited a link
388 dont-wrap-pre (integer) If nonzero, don't wrap preformatted
389 blocks. Defaults to 0.
390 emojify-link (integer) If nonzero, when the text of a link
391 starts with an emoji followed by a space, use that
392 emoji as line prefix. Defaults to 1.
393 enable-colors (integer) If nonzero, enable colours. Defaults to
394 0 if NO_COLORS is set, 1 otherwise.
395 fill-column (integer) If greater than zero, lines of text will
396 be formatted in a way that don't exceed the given
397 number of columns. Defaults to 80.
399 (integer) If nonzero, hide by default the body of
400 the preformatted blocks. Defaults to zero.
401 push-button can be used to toggle the visibility
403 hide-pre-closing-line
404 (integer) If nonzero, hide the closing line of
405 preformatted blocks. Defaults to 0.
407 (integer) If nonzero, hide the start and end line
408 of the preformatted blocks. If both hide-pre-
409 context and hide-pre-blocks are nonzero,
410 preformatted blocks are irremediably hidden.
412 new-tab-url (string) URL for the new tab page. Defaults to
414 olivetti-mode (integer) If nonzero, enable olivetti-mode
416 set-title (integer) If nonzero, set the terminal title to
417 the page title. Defaults to 1.
418 tab-bar-show (integer) If tab-bar-show is -1 hide the tab bar
419 permanently, if 0 show it unconditionally. If
420 it's 1, show the bar only when there is more than
421 one tab. Defaults to 1.
424 Change the styling of the element identified by name. Multiple
425 options may be specified within curly braces. Valid style
427 line the area outside the lines in the body
429 line.compl the completions.
430 line.compl.current the current completion.
431 line.help text in the *Help* buffer.
432 line.text text lines.
433 line.link link lines.
434 line.title1..3 headings
435 line.item item lines.
437 line.pre.start the heading of a preformatted block.
438 line.pre the content of a preformatted block.
439 line.pre.end the closing line of a preformatted
441 minibuffer the minibuffer.
442 modeline the modeline.
444 tabline.tab the non-focused tabs.
445 tabline.current the focused tab.
449 attr prefix [line [trail]]
450 Sets the text attributes. If only one value is given,
451 line and trail default to that; if two values are given
452 then trail defaults to prefix. Each attribute is a
453 comma-separated list of keywords:
454 normal no attributes.
455 standout best highlighting mode for the terminal.
456 underline underlines the text.
457 reverse reverses background/foreground colors.
458 blink makes the text blinking.
460 bold extra bright or bold.
462 Only the style identifiers with the line. prefix accept
463 up to three attributes. The other will only use the
466 bg prefix [line [trail]]
467 Sets the background color. Follows the same behaviour as
468 attr regarding the optional parameters. The colour is
469 one of black, red, green, yellow, blue, magenta, cyan and
470 white; colour0 to colour255 (or color0 to color255) from
471 the 256-colour set; default for the default colour.
473 fg prefix [line [trail]]
474 Sets the foreground color. It behaves just like bg.
477 Sets the prefix for the current line type to prfx and
478 cont as the prefix for the continuation lines (i.e. when
479 a long line gets wrapped.) If cont is not given its value
480 will be the same of prfx.
483 When telescope is started, it inspects the following environment
486 HOME The user's login directory.
488 NO_COLORS To decide whether to use colors or not. The content of the
489 variable doesn't matter.
491 TERM The user's terminal name.
494 ~/.telescope/bookmarks.gmi
497 Default configuration file.
498 ~/.telescope/known_hosts
499 Hash of the certificates for all the known hosts. Each line
500 contains three fields: hostname with optional port number, hash
501 of the certificate and a numeric flag.
503 Lock file used to prevent multiple instance of telescope from
504 running at the same time.
505 ~/.telescope/pages/about_*.gmi
506 Overrides for built-in about: pages.
508 The list of tabs from the last session. Every line identifies a
509 tab and contains three space-separated fields: the full URL, a
510 comma-separated list of attributes and the cached title. Is
511 written by kill-telescope and loaded during startup.
514 It's possible to browse the small web (i.e. simple websites) by using
515 programs like the duckling-proxy by defining a proxy in
518 proxy http via "gemini://127.0.0.1:1965"
519 proxy https via "gemini://127.0.0.1:1965"
521 To load telescope without any configuration
523 telescope -c /dev/null
526 The telescope program was written by Omar Polo <op@omarpolo.com>.
529 There's no UI for out-of-band certificates validation.
531 OpenBSD 7.0 August 27, 2021 OpenBSD 7.0
