---
name: "urlscan"
section: "1"
platform: "linux"
package: "urlscan"
version: "1.2.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/urlscan"
---

# urlscan(1)

browse the URLs in an email message from a terminal

## 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)](/urlview/1.md), 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**. For mail converted from HTML, where the links are gathered into a footnote block and the text carries only a marker such as **\[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 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, and **Esc** clears it.

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

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

- **-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 certain message headers for URLs. Currently Link, Archived-At and List-\* are scanned.

- **-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 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, 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 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.

## SEE ALSO

*/usr/share/doc/urlscan/README*, [**urlview**(1)](/urlview/1.md), [**mutt**(1)](/mutt/1.md)

## AUTHOR

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