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
385 Minibuffer-specific keys
386 enter mini-complete-and-exit
390 del mini-delete-backward-char
391 backspace mini-delete-backward-char
392 C-h mini-delete-backward-char
398 C-a move-beginning-of-line
399 <end> move-end-of-line
400 <home> move-beginning-of-line
402 M-p mini-previous-history-element
403 M-n mini-next-history-element
404 C-p previous-completion
406 <up> previous-completion
407 <down> next-completion
408 tab insert-current-candidate
409 M-< mini-goto-beginning
413 Follows the documentation for the interactive commands. These commands
414 can be bound to a key or executed with execute-extended-command.
417 backward-char Move point one character backward.
418 backward-paragraph Move point one paragraph backward.
419 beginning-of-buffer Move point to the beginning of the buffer.
420 end-of-buffer Move point to the end of the buffer.
421 forward-char Move point one character forward.
422 forward-paragraph Move point one paragraph forward.
423 insert-current-candidate Copy the current selection text as minibuffer
425 move-beginning-of-line Move point at the beginning of the current
427 move-end-of-line Move point at the end of the current (visual)
429 next-button Move point to the next link.
430 next-completion Select the next completion.
431 next-heading Move point to the next heading.
432 next-line Move point to the next (visual) line, in the
433 same column if possible.
434 previous-button Move point to the previous link.
435 previous-completion Select the previous completion.
436 previous-heading Move point to the previous heading.
437 previous-line Move point to the previous (visual) line.
439 Bookmark-related commands
440 bookmark-page Save a page in the bookmark file. It preloads
441 the minibuffer with the current URL.
442 list-bookmarks Load the bookmarks page.
445 tab-close Close the current tab.
446 tab-close-other Close all tabs but the current one.
447 tab-move Move the current tab after the next one,
448 wrapping around if needed.
449 tab-move-to Move the current tab before the previous one,
450 wrapping around if needed.
451 tab-new Open a new tab.
452 tab-next Focus next tab, wrapping around eventually.
453 tab-previous Focus the previous tab, wrapping around
455 tab-select Switch to a tab using the minibuffer.
456 tab-undo-close Re-open the most recently closed tab, if any.
459 cache-info Show cache stats.
460 clear-minibuf Clear the echo area.
461 dec-fill-column Decrement fill-column by two.
462 execute-extended-command Execute an internal command.
463 kill-telescope Quit telescope.
464 inc-fill-column Increment fill-column by two.
465 link-select Select and visit a link using the minibuffer.
466 load-current-url Edit the current URL.
467 load-url Prompt for an URL.
468 next-page Go forward in the page history.
469 olivetti-mode Toggle olivetti mode (i.e. horizontal centering
470 of the lines of the window.)
471 other-window Select the other window.
472 previous-page Go backward in the page history.
473 push-button Follow link at point, or toggle the visibility
474 of the following preformatted block if called
475 when the cursor is on the heading of the block.
476 push-button-new-tab Follow link at point in a new tab.
477 redraw Redraw the screen, useful if some background
478 program messed up the display.
479 reload-page Reload the current page.
480 reply-last-input Reply the last input request.
481 scroll-down Scroll down by one visual page.
482 scroll-line-down Scroll down by one line.
483 scroll-line-up Scroll up by one line.
484 scroll-up Scroll up by one visual page.
485 suspend-telescope Suspend the current telescope session.
486 swiper Jump to a line using the minibuffer.
487 toc Jump to a heading using the minibuffer.
488 toggle-help Toggle side window with help about available
489 keys and their associated interactive command.
490 toggle-pre-wrap Toggle the wrapping of preformatted blocks.
493 mini-abort Abort the current minibuffer action.
494 mini-complete-and-exit Complete the current minibuffer action.
495 mini-delete-backward-char
496 Delete the character before the point.
497 mini-delete-char Delete the character after the point.
498 mini-goto-beginning Select the first completion, if any.
499 mini-goto-end Select the last completion, if any.
500 mini-kill-line Delete from point until the end of the line.
501 mini-next-history-element
502 Load the previous history element.
503 mini-previous-history-element
504 Load the next history element.
507 The following aliases are available during execute-extended-command:
512 q and wq kill-telescope
515 When telescope is started, it inspects the following environment
518 HOME The user's login directory.
520 NO_COLORS To decide whether to use colors or not. The content of the
521 variable doesn't matter.
523 TERM The user's terminal name.
525 XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME
526 If defined can alter the default location of the files used.
529 By default telescope follows the XDG Base Directory Specification.
530 However, if ~/.telescope exists, XDG is ignored and all the files are
531 stored inside it. The usage of XDG_CACHE_HOME, XDG_CONFIG_HOME and
532 XDG_DATA_HOME can further alter the location of these files.
534 ~/.config/telescope/config
535 Default configuration file.
536 ~/.local/share/telescope/pages/about_*.gmi
537 Overrides for built-in about: pages.
538 ~/.local/share/telescope/bookmarks.gmi
540 ~/.local/share/telescope/known_hosts
541 Hash of the certificates for all the known hosts. Each line
542 contains three fields: hostname with optional port number, hash
543 of the certificate and a numeric flag.
544 ~/.cache/telescope/lock
545 Lock file used to prevent multiple instance of telescope from
546 running at the same time.
547 ~/.cache/telescope/session
548 The list of tabs from the last session.
551 It's possible to browse the small web (i.e. simple websites) by using
552 programs like the duckling-proxy by defining a proxy in
553 ~/.config/telescope/config:
555 proxy http via "gemini://127.0.0.1:1965"
556 proxy https via "gemini://127.0.0.1:1965"
558 To load telescope without any configuration
560 telescope -c /dev/null
563 XDG Base Directory Specification,
564 https://specifications.freedesktop.org/basedir-spec/latest/.
567 The Trust, but verify (where appropriate) TOFU scheme was firstly
568 suggested by thfr: gemini://thfr.info/gemini/modified-trust-verify.gmi.
571 The telescope program was written by Omar Polo <op@omarpolo.com>.
574 telescope assumes a UTF-8 environment and doesn't try to cope with other
575 encodings. This can cause strange rendering issues if you're lucky, or
576 possibly weird thing happening depending on your locale and terminal
579 The algorithm used for text-wrapping is naive and doesn't really work for
580 languages that make heavily use of glyphs composed by multiple UNICODE
584 There's no UI for out-of-band certificates validation.
586 OpenBSD 7.1 January 5, 2022 OpenBSD 7.1
