-
Notifications
You must be signed in to change notification settings - Fork 38
/
urlscan.1
221 lines (177 loc) · 7.15 KB
/
urlscan.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
.\" Hey, EMACS: -*- nroff -*-
.TH URLSCAN 1 "1 June 2023"
.SH NAME
urlscan \- browse the URLs in an email message from a terminal
.SH SYNOPSIS
\fBurlscan\fR [options] <
.I message
\fBurlscan\fR [options]
.I message
.SH DESCRIPTION
\fBurlscan\fR accepts a single email message on standard
input, then displays a terminal-based list of the URLs in the given
message. Selecting a URL uses the Python webbrowser module to
determine which browser to open. The \fBBROWSER\fR environment
variable will be used if it is set.
\fBurlscan\fR is primarily intended to be used with the
.B mutt
(1) mailreader, but it should work well with any terminal-based mail
program.
\fBurlscan\fR is similar to \fBurlview\fR(1), but has the following
additional features:
\fB1.\fR Support for more message encodings, such as quoted-printable
and base64.
\fB2.\fR Extraction and display of the context surrounding each URL. Toggle
context view on/off with \fBc\fR. Reverse displayed order of URLs with \fBR\fR.
\fB3.\fR Copy current URL to primary selection with \fBP\fR or to clipboard with
\fBC\fR.
\fB4.\fR URLs are shortened by default to fit on one line. Toggle one or all
shortened URLs with \fBs\fR or \fBS\fR.
\fB5.\fR Incremental case-insensitive search using \fB/\fR. Footer shows current
search term. \fB/\fR again resets search.
\fB6.\fR Cycle through all available palettes (color and black & white available
by default) using \fBp\fR. Running \fBurlscan \-g\fR will generate a
~/.config/urlscan/config.json file for editing or adding additional pallettes
and keybindings. See
http://urwid.org/manual/displayattributes.html#display-attributes
for color options and allowed values. Set display width with `--width`.
\fB7.\fR \fBu\fR will unescape the highlighted URL if necessary.
\fB8.\fR Run a command with the selected URL as the argument or pipe the
selected URL to a command using the \fB--run-safe\fR, \fB--run\fR and
\fB--pipe\fR arguments.
\fB9.\fR Use \fBl\fR to cycle through whether URLs are opened using the Python
webbrowser module (default), xdg-open (if installed) or a function passed on the
command line with \fB--run-safe\fR or \fB--run\fR. The \fB--run\fR and
\fB--run-safe\fR functions will respect the value of \fB--pipe\fR.
\fB10.\fR \fBF1\fR shows the help menu.
\fB11.\fR Scan certain email headers for URLs. Currently \fBLink\fR,
\fBArchived-At\fR and \fBList-*\fR are scanned when \fB--headers\fR is passed.
\fB12.\fR Queue multiple URLs for opening and open them all at once with \fBa\fR and \fBo\fR.
.SH OPTIONS
.TP
.B \-c, \-\-compact
Display a simple list of the extracted URLs, instead of showing the
context of each URL. Also toggle with `c` from within the viewer.
.TP
.B \-d, \-\-dedupe
Remove duplicated URLs from the list of URLs.
.TP
.B \-E, \-\-regex \<expression\>
Use \<expression\> in place of the default set of regular expressions,
to be used for any kind of matching. This is useful for example when
selectively avoiding 'mailto:' links or any other pattern that urlscan
could interpret as urls (such as '<filename>.<extension>'). Usage
example:
$ urlscan --regex 'https?://.+\.\w+' file.txt
.TP
.B \-f, \-\-run\-safe \<expression\>
Execute \<expression\> in place of opening URL with a browser. Use {} in
\<expression\> to substitute in the URL. Examples:
$ urlscan --run-safe 'tmux set buffer {}'
.TP
.B \-g, \-\-genconf
Generate ~/.config/urlscan/config.json with default options.
.TP
.B \-H, \-\-nohelp
Start with header menu hidden.
.TP
.B \-\-headers
Scan email headers for URLs.
.TP
.B \-n, \-\-no-browser
Disables the selection interface and print the links to standard output.
Useful for scripting (implies \fB\-\-compact\fR).
.TP
.B \-p, \-\-pipe
Pipe the selected URL to the command specified by `--run-safe` or `--run`. This
is preferred when the command supports it, as it is more secure and tolerant of
special characters in the URL. Example:
$ urlscan --run-safe 'xclip -i' --pipe file.txt
.TP
.B \-R, \-\-reverse
Reverse displayed order of URLs.
.TP
.B \-r, \-\-run \<expression\>
Execute \<expression\> in place of opening URL with a browser. Use {} in
\<expression\> to substitute in the URL. Shell features such as \| and \> can be
used, but it is less secure. Examples:
$ urlscan --run 'echo {} | xclip -i' file.txt
.TP
.B \-s, \-\-single
Exit urlscan after opening or copying a single browser link.
$ urlscan -s file.txt
.TP
.B \-w, \-\-width
Set display width.
.TP
.B \-W, \-\-whitespace-off
Suppress output of blank lines and ellipses lines.
.SH MUTT INTEGRATION
To integrate urlscan with mutt, include the following two commands in
\fB~/.muttrc\fR:
.ad l
macro index,pager \\cb "<pipe-message> urlscan<Enter>" "call urlscan to extract URLs out of a message"
macro attach,compose \\cb "<pipe-entry> urlscan<Enter>" "call urlscan to extract URLs out of a message"
.ad b
Once these lines are in your mutt configuration file, pressing
Control-b will allow you to browse and open the URLs in the currently
selected message.
Alternately, you can pipe a message into urlscan using the '|' operator. This
can be useful for applying a different flag (such as the '-d' or '-c' options).
.SH KEYBINDINGS
Run \fBurlscan \-g\fR to generate ~/.config/urlscan/config.json. All of the keys
will be listed. You can either leave in place or delete any that will not be
altered.
To unset a binding, set it equal to "". For example: \fB"P": ""\fR
The follow actions are supported:
.TP
\fBadd_url\fR \-\- add a URL to the queue (Default: \fBa\fR)
.TP
\fBall_escape\fR \-\- toggle unescape all URLs (Default: \fBu\fR)
.TP
\fBall_shorten\fR \-\- toggle shorten all URLs (Default: \fBS\fR)
.TP
\fBbottom\fR \-\- move cursor to last item (Default: \fBG\fR)
.TP
\fBclear_screen\fR \-\- redraw screen (Default: \fBCtrl-l\fR)
.TP
\fBclipboard\fR \-\- copy highlighted URL to clipboard using xsel/xclip (Default: \fBC\fR)
.TP
\fBclipboard_pri\fR \-\- copy highlighted URL to primary selection using xsel/xclip (Default: \fBP\fR)
.TP
\fBcontext\fR \-\- show/hide context (Default: \fBc\fR)
.TP
\fBdel_url\fR \-\- delete URL from the queue (Default: \fBd\fR)
.TP
\fBdown\fR \-\- cursor down (Default: \fBj\fR)
.TP
\fBhelp_menu\fR \-\- show/hide help menu (Default: \fBF1\fR)
.TP
\fBlink_handler\fR \-\- cycle link handling (webbrowser, xdg-open or custom) (Default: \fBl\fR)
.TP
\fBopen_queue\fR \-\- open all URLs in queue (Default: \fBo\fR)
.TP
\fBopen_queue_win\fR \-\- open all URLs in queue in new window (Default: \fBO\fR)
.TP
\fBopen_url\fR \-\- open selected URL (Default: \fBspace\fR or \fBenter\fR)
.TP
\fBpalette\fR \-\- cycle through palettes (Default: \fBp\fR)
.TP
\fBquit\fR \-\- quit (Default: \fBq\fR or \fBQ\fR)
.TP
\fBreverse\fR \-\- reverse display order (Default: \fBR\fR)
.TP
\fBshorten\fR \-\- toggle shorten highlighted URL (Default: \fBs\fR)
.TP
\fBtop\fR \-\- move to first list item (Default: \fBg\fR)
.TP
\fBup\fR \-\- cursor up (Default: \fBk\fR)
.SH FILES
$HOME/.config/urlscan/config.json
Only required if additional or modified palettes or keybindings are desired.
.SH SEE ALSO
\fI/usr/share/doc/urlscan/README\fR,
\fBurlview\fR(1),
\fBmutt\fR(1)
.SH AUTHOR
This manual page was written by Daniel Burrows <dburrows@debian.org> and Scott Hansen <tech@firecat53.net>