urlscan(1)

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

OPTIONS

68       -g, --genconf
69              Generate ~/.config/urlscan/config.json with default options.
70
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       -H, --nohelp
77              Start with header menu hidden.
78
79       -d, --dedupe
80              Remove duplicated URLs from the list of URLs.
81
82       -n, --no-browser
83              Disables the selection interface and print the links to standard
84              output.  Useful for scripting (implies --compact).
85
86       -f, --run-safe <expression>
87              Execute <expression> in place of opening URL with a browser. Use
88              {} in <expression> to substitute in the URL. Examples:
89
90                  $ urlscan --run-safe 'tmux set buffer {}'
91
92       -r, --run <expression>
93              Execute <expression> in place of opening URL with a browser. Use
94              {} in <expression> to substitute in the URL. Shell features such
95              as  and > can be used, but it is less secure. Examples:
96
97                  $ urlscan --run 'echo {} | xclip -i' file.txt
98
99       -p, --pipe
100              Pipe  the  selected URL to the command specified by `--run-safe`
101              or `--run`. This is preferred when the command supports  it,  as
102              it is more secure and tolerant of special characters in the URL.
103              Example:
104
105                  $ urlscan --run-safe 'xclip -i' --pipe file.txt
106
107       -R, --reverse
108              Reverse displayed order of URLs.
109
110       -s, --single
111              Exit urlscan after opening or copying a single browser link.
112
113                  $ urlscan -s file.txt
114
115       -w, --width
116              Set display width.
117
118       -E, --regex <expression>
119              Use <expression> in place of the default set of regular  expres‐
120              sions,  to  be used for any kind of matching. This is useful for
121              example when selectively avoiding 'mailto:' links or  any  other
122              pattern  that  urlscan  could interpret as urls (such as '<file‐
123              name>.<extension>'). Usage example:
124
125                  $ urlscan --regex 'https?://.+.240
126
127       --headers
128              Scan email headers for URLs.
129
130

MUTT INTEGRATION

132       To integrate urlscan with mutt, include the following two  commands  in
133       ~/.muttrc:
134
135
136       macro index,pager \cb "<pipe-message> urlscan<Enter>" "call urlscan to
137       extract URLs out of a message"
138
139       macro attach,compose \cb "<pipe-entry> urlscan<Enter>" "call urlscan to
140       extract URLs out of a message"
141
142
143       Once these lines are in your mutt configuration file, pressing Control-
144       b will allow you to browse and open the URLs in the currently  selected
145       message.
146
147       Alternately,  you  can pipe a message into urlscan using the '|' opera‐
148       tor. This can be useful for applying a different flag (such as the '-d'
149       or '-c' options).
150
151

KEYBINDINGS

153       Run  urlscan  -g  to generate ~/.config/urlscan/config.json. All of the
154       keys will be listed. You can either leave in place or delete  any  that
155       will not be altered.
156
157       To unset a binding, set it equal to "". For example: "P": ""
158
159       The follow actions are supported:
160
161       all_escape -- toggle unescape all URLs (Default: u)
162
163       all_shorten -- toggle shorten all URLs (Default: S)
164
165       bottom -- move cursor to last item (Default: G)
166
167       clear_screen -- redraw screen (Default: Ctrl-l)
168
169       clipboard  --  copy  highlighted URL to clipboard using xsel/xclip (De‐
170       fault: C)
171
172       clipboard_pri --  copy  highlighted  URL  to  primary  selection  using
173       xsel/xclip (Default: P)
174
175       context -- show/hide context (Default: c)
176
177       down -- cursor down (Default: j)
178
179       help_menu -- show/hide help menu (Default: F1)
180
181       link_handler  --  cycle  link handling (webbrowser, xdg-open or custom)
182       (Default: l)
183
184       open_url -- open selected URL (Default: space or enter)
185
186       palette -- cycle through palettes (Default: p)
187
188       quit -- quit (Default: q or Q)
189
190       reverse -- reverse display order (Default: R)
191
192       shorten -- toggle shorten highlighted URL (Default: s)
193
194       top -- move to first list item (Default: g)
195
196       up -- cursor up (Default: k)
197
198

FILES

200       $HOME/.config/urlscan/config.json
201
202       Only required if additional or modified palettes are desired.
203
204

AUTHOR

210       This manual page was written by  Daniel  Burrows  <dburrows@debian.org>
211       and Scott Hansen <firecat4153@gmail.com>
212
213
214
215                                 6 March 2021                       URLSCAN(1)