1
2URLSCAN(1)                  General Commands Manual                 URLSCAN(1)
3
4
5

NAME

7       urlscan - browse the URLs in an email message from a terminal
8

SYNOPSIS

10       urlscan [options] < message
11
12       urlscan [options] message
13
14

DESCRIPTION

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
21       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
24       urlscan is similar to urlview(1), but has the following additional fea‐
25       tures:
26
27       1. Support for more message encodings,  such  as  quoted-printable  and
28       base64.
29
30       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
33       3. Copy current URL to primary selection with P or to clipboard with C.
34
35       4. URLs are shortened by default to fit on one line. Toggle one or  all
36       shortened URLs with s or S.
37
38       5.  Incremental  case-insensitive  search using /. Footer shows current
39       search term. / again resets search.
40
41       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
46       http://urwid.org/manual/displayattributes.html#display-attributes
47
48       for color options and allowed values. Set display width with `--width`.
49
50       7. u will unescape the highlighted URL if necessary.
51
52       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
56       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
61       10. F1 shows the help menu.
62
63       11. Scan certain email headers for URLs.  Currently  Link,  Archived-At
64       and List-* are scanned when --headers is passed.
65
66       12.  Queue  multiple  URLs for opening and open them all at once with a
67       and o.
68
69

OPTIONS

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
76       -d, --dedupe
77              Remove duplicated URLs from the list of URLs.
78
79       -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
86                  $ urlscan --regex 'https?://.+.240
87
88       -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
92                  $ urlscan --run-safe 'tmux set buffer {}'
93
94       -g, --genconf
95              Generate ~/.config/urlscan/config.json with default options.
96
97       -H, --nohelp
98              Start with header menu hidden.
99
100       --headers
101              Scan email headers for URLs.
102
103
104       -n, --no-browser
105              Disables the selection interface and print the links to standard
106              output.  Useful for scripting (implies --compact).
107
108       -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
114                  $ urlscan --run-safe 'xclip -i' --pipe file.txt
115
116       -R, --reverse
117              Reverse displayed order of URLs.
118
119       -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
124                  $ urlscan --run 'echo {} | xclip -i' file.txt
125
126       -s, --single
127              Exit urlscan after opening or copying a single browser link.
128
129                  $ urlscan -s file.txt
130
131       -w, --width
132              Set display width.
133
134       -W, --whitespace-off
135              Suppress output of blank lines and ellipses lines.
136
137

MUTT INTEGRATION

139       To  integrate  urlscan with mutt, include the following two commands in
140       ~/.muttrc:
141
142
143       macro index,pager \cb "<pipe-message> urlscan<Enter>" "call urlscan to
144       extract URLs out of a message"
145
146       macro attach,compose \cb "<pipe-entry> urlscan<Enter>" "call urlscan to
147       extract URLs out of a message"
148
149
150       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
154       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
158

KEYBINDINGS

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
164       To unset a binding, set it equal to "". For example: "P": ""
165
166       The follow actions are supported:
167
168       add_url -- add a URL to the queue (Default: a)
169
170       all_escape -- toggle unescape all URLs (Default: u)
171
172       all_shorten -- toggle shorten all URLs (Default: S)
173
174       bottom -- move cursor to last item (Default: G)
175
176       clear_screen -- redraw screen (Default: Ctrl-l)
177
178       clipboard -- copy highlighted URL to clipboard  using  xsel/xclip  (De‐
179       fault: C)
180
181       clipboard_pri  --  copy  highlighted  URL  to  primary  selection using
182       xsel/xclip (Default: P)
183
184       context -- show/hide context (Default: c)
185
186       del_url -- delete URL from the queue (Default: d)
187
188       down -- cursor down (Default: j)
189
190       help_menu -- show/hide help menu (Default: F1)
191
192       link_handler -- cycle link handling (webbrowser,  xdg-open  or  custom)
193       (Default: l)
194
195       open_queue -- open all URLs in queue (Default: o)
196
197       open_queue_win -- open all URLs in queue in new window (Default: O)
198
199       open_url -- open selected URL (Default: space or enter)
200
201       palette -- cycle through palettes (Default: p)
202
203       quit -- quit (Default: q or Q)
204
205       reverse -- reverse display order (Default: R)
206
207       shorten -- toggle shorten highlighted URL (Default: s)
208
209       top -- move to first list item (Default: g)
210
211       up -- cursor up (Default: k)
212
213

FILES

215       $HOME/.config/urlscan/config.json
216
217       Only required if additional or modified palettes or keybindings are de‐
218       sired.
219
220

SEE ALSO

222       /usr/share/doc/urlscan/README, urlview(1), mutt(1)
223
224

AUTHOR

226       This manual page was written by  Daniel  Burrows  <dburrows@debian.org>
227       and Scott Hansen <tech@firecat53.net>
228
229
230
231                                  1 June 2023                       URLSCAN(1)
Impressum