Scott Hansen \tech@firecat53.net\ (Author and Maintainer)
Maxime Chatelle \xakz@rxsoft.eu\ (Debian Maintainer)
Daniel Burrows \dburrows@debian.org\ (Original Author)
Urlscan is a small program that is designed to integrate with the "mutt" mailreader to allow you to easily launch a Web browser for URLs contained in email messages. It is a replacement for the "urlview" program.
Requires: Python 3.7+ and the python-urwid library
Urlscan parses an email message or file and scans it for URLs and email addresses. It then displays the URLs and their context within the message, and allows you to choose one or more URLs to send to your Web browser. Alternatively, it send a list of all URLs to stdout.
Relative to urlview, urlscan has the following additional features:
Support for emails in quoted-printable and base64 encodings. No more stripping out =40D from URLs by hand!
The context of each URL is provided along with the URL. For HTML mails, a
crude parser is used to render the HTML into text. Context view can be toggled
on/off with c
.
URLs are shortened by default to fit on one line. Viewing full URL (for one or
all) is toggled with s
or S
.
Jump to a URL by typing the number.
Incremental case-insensitive search with /
.
Execute an arbitrary function (for example, copy URL to clipboard) instead of opening URL in a browser.
Use l
to cycle through whether URLs are opened using the Python webbrowser
module (default), xdg-open (if installed) or opened by a function passed on
the command line with --run
or --run-safe
.
Configure colors and keybindings via ~/.config/urlscan/config.json. Generate
default config file for editing by running urlscan -g
. Cycle through
available palettes with p
. Set display width with --width
.
Copy URL to clipboard with C
or to primary selection with P
. Requires
xsel or xclip.
Run a command with the selected URL as the argument or pipe the selected URL to a command.
Show complete help menu with F1
. Hide header on startup with --nohelp
.
Use a custom regular expression with -E
for matching urls or any
other pattern. In junction with -r
, this effectively turns urlscan
into a general purpose CLI selector-type utility.
Scan certain email headers for URLs. Currently Link
, Archived-At
and
List-*
are scanned when --headers
is passed.
Queue multiple URLs for opening and open them all at once with a
and o
.
To install urlscan, install from your distribution repositories, from Pypi, or do a local development install with pip -e:
pipx install urlscan
OR
pip install --user urlscan
OR
cd <path/to/urlscan> && pip install --user -e .
NOTE
The minimum required version of urwid is 1.2.1.
Once urlscan is installed, add the following lines to your .muttrc:
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"
Once this is done, Control-b while reading mail in mutt will automatically invoke urlscan on the message.
Note for Neomutt users: As of version
2023-05-17
true color support was implemented. If you are using true color support with Neomutt, or are encountering the errorsetupterm: could not find terminfo database
, then you should also addTERM=xterm-256color
to your macro in.muttrc
. See more here #135. For example:macro index,pager \cb "<pipe-message> TERM=xterm-256color urlscan<Enter>" "call urlscan to extract URLs out of a message"
To choose a particular browser, set the environment variable BROWSER. If BROWSER is not set, xdg-open will control which browser is used, if it's available.:
export BROWSER=/usr/bin/epiphany
urlscan OPTIONS <file>
OPTIONS [-c, --compact]
[-d, --dedupe]
[-E, --regex <expression>]
[-f, --run-safe <expression>]
[-g, --genconf]
[-H, --nohelp]
[ --headers]
[-n, --no-browser]
[-p, --pipe]
[-r, --run <expression>]
[-R, --reverse]
[-s, --single]
[-w, --width]
[-W --whitespace-off]
Urlscan can extract URLs and email addresses from emails or any text file. Calling with no flags will start the curses browser. Calling with '-n' will just output a list of URLs/email addressess to stdout. The '-c' flag removes the context from around the URLs in the curses browser, and the '-d' flag removes duplicate URLs. The '-R' flag reverses the displayed order of URLs and context. Files can also be piped to urlscan using normal shell pipe mechanisms: `cat