URLSCAN(1)

✨ URLSCAN(1) ✨ — the terminal URL browser for your email, bestie 💌

okay so picture this: you're in mutt, someone sent you a message with like fourteen links in it, and you are NOT about to copy-paste each one like a peasant. enter urlscan, a General Commands Manual girly who browses the URLs in an email message from a terminal. she's giving main character energy and she's literally about to fix your whole life. 🫶

---

🌸 NAME 🌸

urlscan — browse the URLs in an email message from a terminal

---

🎀 SYNOPSIS 🎀

urlscan [options] < message

urlscan [options] message

---

💖 DESCRIPTION 💖

so urlscan takes a single email message on standard input, and then it pops off by showing you a terminal-based list of all the URLs in that message. when you select one, it uses the Python webbrowser module to figure out which browser should open it. and if the BROWSER environment variable is set, that's what gets used. periodt.

she's primarily meant to be used with the mutt(1) mailreader, but ngl she should work just fine with any terminal-based mail program. versatile queen. 👑

urlscan is similar to urlview(1), but she has these extra features, and honestly? obsessed:

1. support for more message encodings, like quoted-printable and base64.
2. extraction and display of the context surrounding each URL. toggle that context view on/off with c. reverse the displayed order of URLs with R. for mail that got converted from HTML, where the links are all gathered into a footnote block and the text just carries a marker like [1], the prose around that marker is shown instead of the footnote line. the styles written by w3m -dump, lynx -dump and markdown are recognised.
3. copy the current URL to the primary selection with P, or to the clipboard with C.
4. URLs are shortened by default so they fit on one line. toggle one shortened URL, or all of them, with s or S.
5. incremental case-insensitive search using /. the footer shows your current search term. / again resets the search, and Esc clears it.
6. cycle through all available palettes (color and black & white are available by default) using p. running urlscan -g will generate a ~/.config/urlscan/config.json file so you can edit it or add additional palettes and keybindings. see

http://urwid.org/manual/displayattributes.html#display-attributes

for color options and allowed values. set the 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 or ? 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 — compact display mode; don't show the context of each URL. minimalism, we love her.
• -d, --dedupe — remove duplicated URLs from the list of URLs. no dupes allowed in this house.
• -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?://.+.240

• -f, --run-safe <expression> — execute <expression> in place of opening the 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. your starter kit bestie 🎀
• -H, --nohelp — start with the header menu hidden.
• --headers — scan certain message headers for URLs. currently Link, Archived-At and List-* are scanned.
• -n, --no-browser — disables the selection interface and prints 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 the 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 or queue of links.

$ urlscan -s file.txt

• -w, --width — set display width.
• -W, --whitespace-off — don't display empty lines and ellipses.
• -C, --colors {true,256,88,16,8,mono} — set the urwid color mode. default is "16". "true" = 2**24 colors and "mono" = 1 color.
• -V, --version — print urlscan version.

---

🦋 MUTT INTEGRATION 🦋

to integrate urlscan with mutt, drop these two commands into ~/.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 Ctrl+b will let you browse and open the URLs in the currently selected message. iconic behavior fr fr.

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 space bar can be written as "space" or " ".

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_search -- clear the search and show all URLs (Default: Esc)
• 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 or ?)
• link_handler -- cycle link handling (webbrowser, xdg-open or custom) (Default: l)
• next -- jump to next URL (Default: J)
• 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)
• previous -- jump to previous URL (Default: K)
• 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. no config, no problem 💅

---

🧚 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>

---

okay bestie that's the whole page, you ate that 💖 this was the urlscan manual page, dated 11 October 2026 — go forth and open your links, you absolute legend. 🎀✨🦋