1URLSCAN(1) General Commands Manual URLSCAN(1)
3
7 urlscan - browse the URLs in an email message from a terminal
8
10 urlscan [options] < message
11 urlscan [options] message
13
16 urlscan accepts a single email message on standard input, then displays
17 a terminal-based list of the URLs in the given message. Selecting a
18 URL uses the Python webbrowser module to determine which browser to
19 open. The BROWSER environment variable will be used if it is set.
20 urlscan is primarily intended to be used with the mutt (1) mailreader,
22 but it should work well with any terminal-based mail program.
23 urlscan is similar to urlview(1), but has the following additional fea‐
25 tures:
26 1. Support for more message encodings, such as quoted-printable and
28 base64.
29 2. Extraction and display of the context surrounding each URL. Toggle
31 context view on/off with c. Reverse displayed order of URLs with R.
32 3. Copy current URL to primary selection with P or to clipboard with C.
34 4. URLs are shortened by default to fit on one line. Toggle one or all
36 shortened URLs with s or S.
37 5. Incremental case-insensitive search using /. Footer shows current
39 search term. / again resets search.
40 6. Cycle through all available palettes (color and black & white avail‐
42 able by default) using p. Running urlscan -g will generate a ~/.con‐
43 fig/urlscan/config.json file for editing or adding additional pallettes
44 and keybindings. See
45 http://urwid.org/manual/displayattributes.html#display-attributes
47 for color options and allowed values. Set display width with `--width`.
49 7. u will unescape the highlighted URL if necessary.
51 8. Run a command with the selected URL as the argument or pipe the se‐
53 lected URL to a command using the --run-safe, --run and --pipe argu‐
54 ments.
55 9. Use l to cycle through whether URLs are opened using the Python web‐
57 browser module (default), xdg-open (if installed) or a function passed
58 on the command line with --run-safe or --run. The --run and --run-safe
59 functions will respect the value of --pipe.
60 10. F1 shows the help menu.
62 11. Scan certain email headers for URLs. Currently Link, Archived-At
64 and List-* are scanned when --headers is passed.
65 12. Queue multiple URLs for opening and open them all at once with a
67 and o.
68
71 -c, --compact
72 Display a simple list of the extracted URLs, instead of showing
73 the context of each URL. Also toggle with `c` from within the
74 viewer.
75 -d, --dedupe
77 Remove duplicated URLs from the list of URLs.
78 -E, --regex <expression>
80 Use <expression> in place of the default set of regular expres‐
81 sions, to be used for any kind of matching. This is useful for
82 example when selectively avoiding 'mailto:' links or any other
83 pattern that urlscan could interpret as urls (such as '<file‐
84 name>.<extension>'). Usage example:
85 $ urlscan --regex 'https?://.+.240
87 -f, --run-safe <expression>
89 Execute <expression> in place of opening URL with a browser. Use
90 {} in <expression> to substitute in the URL. Examples:
91 $ urlscan --run-safe 'tmux set buffer {}'
93 -g, --genconf
95 Generate ~/.config/urlscan/config.json with default options.
96 -H, --nohelp
98 Start with header menu hidden.
99 --headers
101 Scan email headers for URLs.
102 -n, --no-browser
105 Disables the selection interface and print the links to standard
106 output. Useful for scripting (implies --compact).
107 -p, --pipe
109 Pipe the selected URL to the command specified by `--run-safe`
110 or `--run`. This is preferred when the command supports it, as
111 it is more secure and tolerant of special characters in the URL.
112 Example:
113 $ urlscan --run-safe 'xclip -i' --pipe file.txt
115 -R, --reverse
117 Reverse displayed order of URLs.
118 -r, --run <expression>
120 Execute <expression> in place of opening URL with a browser. Use
121 {} in <expression> to substitute in the URL. Shell features such
122 as and > can be used, but it is less secure. Examples:
123 $ urlscan --run 'echo {} | xclip -i' file.txt
125 -s, --single
127 Exit urlscan after opening or copying a single browser link.
128 $ urlscan -s file.txt
130 -w, --width
132 Set display width.
133 -W, --whitespace-off
135 Suppress output of blank lines and ellipses lines.
136
139 To integrate urlscan with mutt, include the following two commands in
140 ~/.muttrc:
141 macro index,pager \cb "<pipe-message> urlscan<Enter>" "call urlscan to
144 extract URLs out of a message"
145 macro attach,compose \cb "<pipe-entry> urlscan<Enter>" "call urlscan to
147 extract URLs out of a message"
148 Once these lines are in your mutt configuration file, pressing Control-
151 b will allow you to browse and open the URLs in the currently selected
152 message.
153 Alternately, you can pipe a message into urlscan using the '|' opera‐
155 tor. This can be useful for applying a different flag (such as the '-d'
156 or '-c' options).
157
160 Run urlscan -g to generate ~/.config/urlscan/config.json. All of the
161 keys will be listed. You can either leave in place or delete any that
162 will not be altered.
163 To unset a binding, set it equal to "". For example: "P": ""
165 The follow actions are supported:
167 add_url -- add a URL to the queue (Default: a)
169 all_escape -- toggle unescape all URLs (Default: u)
171 all_shorten -- toggle shorten all URLs (Default: S)
173 bottom -- move cursor to last item (Default: G)
175 clear_screen -- redraw screen (Default: Ctrl-l)
177 clipboard -- copy highlighted URL to clipboard using xsel/xclip (De‐
179 fault: C)
180 clipboard_pri -- copy highlighted URL to primary selection using
182 xsel/xclip (Default: P)
183 context -- show/hide context (Default: c)
185 del_url -- delete URL from the queue (Default: d)
187 down -- cursor down (Default: j)
189 help_menu -- show/hide help menu (Default: F1)
191 link_handler -- cycle link handling (webbrowser, xdg-open or custom)
193 (Default: l)
194 open_queue -- open all URLs in queue (Default: o)
196 open_queue_win -- open all URLs in queue in new window (Default: O)
198 open_url -- open selected URL (Default: space or enter)
200 palette -- cycle through palettes (Default: p)
202 quit -- quit (Default: q or Q)
204 reverse -- reverse display order (Default: R)
206 shorten -- toggle shorten highlighted URL (Default: s)
208 top -- move to first list item (Default: g)
210 up -- cursor up (Default: k)
212
215 $HOME/.config/urlscan/config.json
216 Only required if additional or modified palettes or keybindings are de‐
218 sired.
219
222 /usr/share/doc/urlscan/README, urlview(1), mutt(1)
223
226 This manual page was written by Daniel Burrows <dburrows@debian.org>
227 and Scott Hansen <tech@firecat53.net>
228 1 June 2023 URLSCAN(1)