URLSCAN(1)                  General Commands Manual                 URLSCAN(1)




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

SYNOPSIS
       urlscan [options] < message

       urlscan [options] message


DESCRIPTION
       urlscan 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 BROWSER environment variable will be used if it is set.

       urlscan is primarily intended to be used with the mutt (1) mailreader,
       but it should work well with any terminal-based mail program.

       urlscan is similar to urlview(1), but has the following additional
       features:

       1. Support for more message encodings, such as quoted-printable and
       base64.

       2. Extraction and display of the context surrounding each URL. Toggle
       context view on/off with c. Reverse displayed order of URLs with R.

       3. Copy current URL to primary selection with P or to clipboard with C.

       4. URLs are shortened by default to fit on one line. Toggle one or all
       shortened URLs with s or S.

       5. Incremental case-insensitive search using /. Footer shows current
       search term. / again resets search.

       6. Cycle through all available palettes (color and black & white
       available by default) using p. Running urlscan -g 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`.

       7. u will unescape the highlighted URL if necessary.

       8. Run a command with the selected URL as the argument or pipe the
       selected URL to a command using the --run-safe, --run and --pipe
       arguments.

       9. Use l 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 --run-safe or --run. The --run and
       --run-safe functions will respect the value of --pipe.

       10. F1 shows the help menu.

       11. Scan certain email headers for URLs. Currently Link, Archived-At
       and List-* are scanned when --headers is passed.

       12. Queue multiple URLs for opening and open them all at once with a
       and o.


OPTIONS
       -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.

       -d, --dedupe
              Remove duplicated URLs from the list of URLs.

       -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?://.+.216

       -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 {}'

       -g, --genconf
              Generate ~/.config/urlscan/config.json with default options.

       -H, --nohelp
              Start with header menu hidden.

       --headers
              Scan email headers for URLs.


       -n, --no-browser
              Disables the selection interface and print the links to standard
              output.  Useful for scripting (implies --compact).

       -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

       -R, --reverse
              Reverse displayed order of URLs.

       -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

       -s, --single
              Exit urlscan after opening or copying a single browser link.

                  $ urlscan -s file.txt

       -w, --width
              Set display width.

       -W, --whitespace-off
              Suppress output of blank lines and ellipses lines.


MUTT INTEGRATION
       To integrate urlscan with mutt, include the following two commands in
       ~/.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 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).


KEYBINDINGS
       Run urlscan -g 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: "P": ""

       The follow actions are supported:

       add_url -- add a URL to the queue (Default: a)

       all_escape -- toggle unescape all URLs (Default: u)

       all_shorten -- toggle shorten all URLs (Default: S)

       bottom -- move cursor to last item (Default: G)

       clear_screen -- redraw screen (Default: Ctrl-l)

       clipboard -- copy highlighted URL to clipboard using xsel/xclip
       (Default: C)

       clipboard_pri -- copy highlighted URL to primary selection using
       xsel/xclip (Default: P)

       context -- show/hide context (Default: c)

       del_url -- delete URL from the queue (Default: d)

       down -- cursor down (Default: j)

       help_menu -- show/hide help menu (Default: F1)

       link_handler -- cycle link handling (webbrowser, xdg-open or custom)
       (Default: l)

       open_queue -- open all URLs in queue (Default: o)

       open_queue_win -- open all URLs in queue in new window (Default: O)

       open_url -- open selected URL (Default: space or enter)

       palette -- cycle through palettes (Default: p)

       quit -- quit (Default: q or Q)

       reverse -- reverse display order (Default: R)

       shorten -- toggle shorten highlighted URL (Default: s)

       top -- move to first list item (Default: g)

       up -- cursor up (Default: k)


FILES
       $HOME/.config/urlscan/config.json

       Only required if additional or modified palettes or keybindings are
       desired.


SEE ALSO
       /usr/share/doc/urlscan/README, urlview(1), mutt(1)


AUTHOR
       This manual page was written by Daniel Burrows <dburrows@debian.org>
       and Scott Hansen <tech@firecat53.net>

                                  1 June 2023                       URLSCAN(1)