______  _     _  ______   _______  ______   _______  _  _  _
          / _____)(_)   (_)(_____ \ (_______)(_____ \ (_______)(_)(_)(_)
         ( (____   _     _  _____) ) _____    _____) ) _______  _  _  _
          \____ \ | |   | ||  __  / |  ___)  |  __  / |  ___  || || || |
          _____) )| |___| || |  \ \ | |      | |  \ \ | |   | || || || |
         (______/  \_____/ |_|   |_||_|      |_|   |_||_|   |_| \_____/
         Surfraw - Shell Users' Revolutionary Front Rage Against the Web

About Surfraw | News | List of Elvi | Downloading | Installation | Usage | Configuration | Development and Support

Oh Baybee
I need some
Deep Linking
Let us go
Surfin' in the raw!

About Surfraw

Surfraw provides a fast unix command line interface to a variety of popular WWW search engines and other artifacts of power. It reclaims google, altavista, babelfish, dejanews, freshmeat, research index, slashdot and many others from the false-prophet, pox-infested heathen lands of html-forms, placing these wonders where they belong, deep in unix heartland, as god loving extensions to the shell.

Surfraw abstracts the browser away from input. Doing so lets it get on with what it's good at. Browsing. Interpretation of linguistic forms is handed back to the shell, which is what it, and human beings are good at. Combined with netscape-remote or incremental text browsers, such as lynx, links or w3m, along with screen a Surfraw liberateur is capable of navigating speeds that leave GUI tainted idolaters agape with fear and wonder.

For example:

         $ surfraw google -results=100 RMS, GNU, which is sinner, which is sin?
         $ sr wikipedia surfraw
         $ sr austlii -method=phrase dog like
         $ /usr/lib/surfraw/rhyme -method=perfect Julian


Current surfraw version: 2.3.0

Thu May 6 20:20:09 BST 2010 - surfraw 2.2.7

Fri Nov 20 03:34:19 GMT 2009 - surfraw 2.2.6

Tue Jul 21 20:44:59 BST 2009 - Migrated CVS repository to git

The surfraw source code repository is now hosted in git.

The repository can be browsed at http://git.debian.org/?p=surfraw/surfraw.git and can be checked out with:

git clone git://git.debian.org/surfraw/surfraw.git

Wed May 13 02:30:21 BST 2009 - surfraw 2.2.5

Sun Mar 1 02:12:14 GMT 2009 - surfraw 2.2.4

Sat Sep 13 20:40:01 BST 2008 - surfraw 2.2.3

Thu Jul 3 08:47:14 BST 2008 - surfraw 2.2.2

March 9th, 2008 - Released Surfraw 2.2.1

September 14th, 2007 - Resumed making upstream releases.

Surfraw is now maintained by the Debian Surfraw-Devel Team. Please report bugs to surfraw-devel@lists.alioth.debian.org, and feel free to join us on the list.

There have been many changes since the last official release:

Old news entries can be viewed here. For a full list of changes to surfraw, consult the ChangeLog file from the surfraw source distribution. Earlier log entries were kept in debian/changelog.


The current version of surfraw is 2.3.0

Current release tarball: surfraw-2.3.0.tar.gz
[MD5] [SHA1] [GPG SIG]

surfraw-2.3.0.tar.gz is signed by the surfraw release key, also available from keyservers.

Debian packages:

Debian surfraw binary package (all architectures) surfraw_2.3.0-1_all.deb
Debian surfraw-extra binary package (all architectures) surfraw-extra_2.3.0-1_all.deb
Debian source package surfraw_2.3.0-1.dsc

Older versions are available here.


Source Tarball

Unpack the source with

gzip -dc surfraw-2.3.0.tar.gz | tar xvvf -

Then, change into the surfraw-2.3.0 directory, and type



then, as root,

make install

This will install surfraw into /usr/local/

For more detailed installation instructions, see the INSTALL file that is part of the surfraw distribution.

Note that the opensearch elvis depends on the perl libraries WWW::OpenSearch, HTML::Parser and LWP (libwww-perl). If you don't want to install opensearch, use

./configure --disable-opensearch

Debian Binary Package

To install the version in your Debian distribution, as root, type:

apt-get install surfraw surfraw-extra

To install the .deb files directly, as root, type:

dpkg -i surfraw_2.3.0-1_all.deb surfraw-extra_2.3.0-1_all.deb

Note that calling dpkg directly does not automatically install dependencies, and surfraw-extra in particular has many dependencies, so it is best to stick with apt-get install where possible.

Debian source package

First you need to ensure you have the necessary packages installed to successfully build surfraw.

The following commands (run as root) should ensure you have everything necessary to build surfraw:

apt-get install build-essential fakeroot
apt-get build-dep surfraw

Download the surfraw_2.3.0-1.dsc, surfraw_2.3.0-1.diff.gz and surfraw_2.3.0.orig.tar.gz files, then type:

dpkg-source -x surfraw_2.3.0-1.dsc

This will unpack the source into a subdirectory called surfraw-2.3.0

Change into this directory, and type:

fakeroot debian/rules binary

This should produce files called surfraw_2.3.0-1_all.deb and surfraw-extra_2.3.0-1_all.deb in the directory above the surfraw source directory. To install these files, type as root:

dpkg -i surfraw_2.3.0-1_all.deb surfraw-extra_2.3.0-1_all.deb

List of Elvi

Surfraw contains the following web site search scripts (elvi)

S Search using custom search provider
W Activate Surfraw defined web-browser
acronym Look for acronyms definitions (www.acronymfinder.com)
ads Search SAO/NASA Astrophysics Data System
alioth Search Alioth (alioth.debian.org)
amazon Search the amazon.com bookstore
archpkg Search Arch Linux Packages (www.archlinux.org/packages/)
archwiki Search the Arch Linux Wiki
arxiv Search arXiv E-Print Archive for articles
ask Question the web using Ask Jeeves (www.ask.com)
aur Search aur.archlinux.org for PKGBUILDs
austlii Search Australian Law docs (www.austlii.edu.au)
bbcnews Search BBC News (news.bbc.co.uk)
bing Search the web using Microsoft's Bing (www.bing.com)
bookfinder Search for books using www.bookfinder.com
bugmenot Bypass compulsory web registration with bugmenot.com
bugzilla Search for bugs on Bugzilla bugtrackers
cia Search CIA documents at www.cia.gov
cisco Search Cisco documentation (www.cisco.com)
cite Search computer science papers (citeseerx.ist.psu.edu)
cliki Search the common lisp wiki
cnn Search on CNN (cnn.com)
comlaw Search Australian Law using Comlaw (www.comlaw.gov.au)
commandlinefu search on www.commandlinefu.com
ctan Search the Comprehensive TeX Archive Network (ctan.org)
currency Convert currencies with the Universal Currency Converter (www.xe.net/ucc)
cve Search for CAN assignments in CVE
debbugs Search the debian BTS (bugs.debian.org)
debcodesearch Search debian source code
debcontents Search contents of debian/ubuntu packages (packages.debian.org/packages.ubuntu.com)
deblists Search debian mailing lists (lists.debian.org/search.html)
deblogs Show changelogs for a package in Debian main (changelogs.debian.net)
debpackages Search debian/ubuntu packages (packages.debian.org/packages.ubuntu.com)
debpkghome Visit the home page for a Debian package
debpts Search the Debian Package Tracking System (packages.qa.debian.org)
debsec Search the Debian Security Tracker for CVE ids or package names
debvcsbrowse Browse the VCS repository for a Debian package
debwiki Search the Debian Wikis (wiki.debian.org & women.debian.org/wiki)
deja Search usenet using Google Groups (groups.google.com)
discogs Search the Discogs database of music information (www.discogs.com)
duckduckgo Securely search the web using duckduckgo (duckduckgo.com)
ebay Search the Ebay auction site
etym Look up word origins at www.etymonline.com
excite Search on Excite (www.excite.com)
f5 Search F5 related information (www.f5.com)
finkpkg Search Fink packages (pdb.finkproject.org)
foldoc The Free On-Line Dictionary Of Computing (foldoc.org)
freebsd Search FreeBSD related information (www.freebsd.org)
freedb Search for cd track listings in FreeDB (www.freedb.org)
freshmeat Search Freshmeat (www.freshmeat.net)
fsfdir Search the FSF/UNESCO Free Software Directory (directory.fsf.org)
gcache Search the web using Google cache (www.google.com)
genbugs Search the Gentoo bug tracker (bugs.gentoo.org)
genportage Search gentoo-portage.com for packages
github Search GitHub (https://github.com)
gmane Search mailing list with gmane (gmane.org)
google Search the web using Google (www.google.com)
gutenberg Search for books on Project Gutenberg (gutenberg.org)
imdb Search the Internet Movie Database (www.imdb.com)
ixquick Search the web using ixquick [HTTPS] (www.ixquick.com)
jamendo Search Jamendo: free music with Creative Commons licenses (www.jamendo.com)
javasun Search Java API docs (java.sun.com)
jquery Search the jQuery documentation (api.jquery.com)
l1sp Search lisp documentation
lastfm Search last.fm
leodict Search Leo's German <-> English dictionary (dict.leo.org)
lsm Search the Linux Software Map
macports Search macports packages (macports.org)
mathworld Search Wolfram MathWorld
mdn Search the mozilla developer network (developer.mozilla.org)
mininova Search the mininova bittorent source.
musicbrainz Search MusicBrainz (musicbrainz.org)
mysqldoc Search mysql documentation (dev.mysql.com)
netbsd Search NetBSD related information (www.netbsd.org)
nlab Search the nLab Wiki (http://ncatlab.org)
ntrs Search the NASA Technical Report Server
openbsd Search OpenBSD related information (www.openbsd.org)
oraclesearch Search Oracle (search.oracle.com)
pgdoc Search postgres documentation (www.pgdoc.com)
pgpkeys Search the PGP key database
phpdoc Search PHP documentation (php.net)
pin Search Pinboard bookmarks (https://pinboard.in)
piratebay Search The Pirate Bay (https://thepiratebay.org)
priberam Look up word in Priberam online dictionary (www.priberam.pt/dlpo)
pubmed Search medical/molbio databases (www.ncbi.nlm.nih.gov)
rae Busca en el diccionario de la Real Academia de la Lengua Española (Spanish Dictionary)
rfc Search RFCs (internet standards documents)
scholar Search Google Scholar (scholar.google.com)
scpan Search the Comprehensive Perl Archive Network (metacpan.org)
searx Search using searx metasearch engine instances (https://searx.me and others)
slashdot Search stories on Slashdot (www.slashdot.org)
slinuxdoc Search entries in LDP (www.linuxdoc.org)
sourceforge Search SourceForge (www.sourceforge.net)
springer Search Springer for Books and Articles
stack Search Stack Overflow
stockquote Get a single stock quote (multiple providers)
thesaurus Look up a synonym in Oxford's thesaurus (en.oxforddictionaries.com)
translate Translate human languages
urban Search urbandictionary.com for a definition
w3css Validate a CSS URL with the w3c CSS validator (jigsaw.w3.org/css-validator)
w3html Validate a web page URL with the w3c validator (validator.w3.org)
w3link Check web page links with the w3c linkchecker (validator.w3.org/checklink)
w3rdf Validate a RDF URL with the w3c RDF validator (validator.w3.org)
wayback Search The Internet Archive's Wayback Machine for a URL (archive.org)
webster Look up word in Merriam-Webster's Dictionary (www.m-w.com)
wikipedia Search the free encyclopedia wikipedia
wiktionary Search the free dictionary wiktionary
woffle Search the web using Woffle (localhost:8080)
wolfram Ask questions of the computational knowledge engine
worldwidescience Search for science with www.worldwidescience.org
yahoo Search Yahoo categories (www.yahoo.com)
yandex Search the web using Yandex (yandex.ru)
youtube Search YouTube (www.youtube.com)


Surfraw consists of a collection of elvi, each of which knows how to search a specific web site.

To see the list of elvi type:

surfraw -elvi

Note that sr is an alias for surfraw, so that could equally be:

sr -elvi

To search using an elvis use:

sr elviname [options] search terms..

For example, to search google for information on Debian ports, using the "I'm feeling lucky" option:

sr google -l debian ports

Note that putting quotes round arguments works now, so you can do, for example:

sr google foo "bar baz" bam

and the quoting is passed on to the search engine.

Adding the elvi to your path

If you are a regular user of surfraw, you will probably get sick of typing sr or surfraw each time. You can regain the old behaviour of running the elvi directly by adding the elvi directory (usually /usr/lib/surfraw/ or /usr/local/lib/surfraw/) to your path, either manually or using surfraw-update-path(1).


Surfraw now supports bookmarks. To add a bookmark, add it to /etc/surfraw.bookmarks or $HOME/.surfraw.bookmarks

The format of the bookmarks file is simple, each bookmark is on a separate line, with the bookmark and URL separated by whitespace, for example:

ntk http://www.ntk.net/

To invoke a bookmark, use surfraw bookmark or sr bookmark, and if an elvis of that name doesn't exist, it searches for a bookmark of that name instead.

There are some example bookmarks in /etc/surfraw.bookmarks


Surfraw has support for bash completion. If bash completion is enabled you can use the <TAB> key to complete elvi names, options and arguments.


Global options are common to all Surfraw elvi (clients). You can get a list of the currently installed elvi by typing surfraw -elvi.

All elvi have useful low calorie help, for example:

$ sr rhyme -help
Usage: rhyme [options] [search words]...
  Surfraw search for rhymes and other word correlations using
  Lycos Rhyme (http://rhyme.lycos.com)
  $ surfraw rhyme Julian
  $ sr rhyme -method=rel surfer
  Hurclean St. Julien.
  surfboarder, bather, natator, swimmer
Local options:
  -method=                      Type of word correlation to search for
          prefect       |       Perfect rhyme
          syn           |       Synonyms
          hom           |       Homophones
          cons          |       Consonsant rhymes only
          rel           |       Semantically related words
          sub           |       Phrases
          spell         |       Similar spellings
          pic           |       Pictures
          shake         |       Match with Shakespeare archives
          def                   Find wordnet definition
                                Default: perfect
                                Environment: SURFRAW_rhyme_method
Global options:
  -browser=EXECUTABLE           Set browser
                                Default: mozilla
  -elvi                         List Surfraw mechanisms for conquering evil
  -escape-url-args=yes|no       Apply url escaping to arguments
                                Default: yes
                                Environment: SURFRAW_escape_url_args
  -g | -graphical               Get some windowed sin
  -help                         What you're reading now, dude
  -quiet=yes|no                 I can't enjoy it with you talking all the time
                                Default: no
                                Environment: SURFRAW_quiet
  -new[=yes|no]                 Start in a new window
                                Default: no
                                Environment: SURFRAW_new_window
  -t | -text                    Back to the yellow brick road
  -q | -quote                   Quote arguments with " characters
                                Default: no
                                Environment: SURFRAW_quote_args
  -version                      Display Surfraw version (1.0.4)
  Copyright (c) 2003-2007 The Surfraw-Devel Team
  Copyright (c) 2000-2001 Julian Assange
  Copyright (c) 2001 Australian Institute for Collaborative Research
  Copyright (c) 2000 Melbourne Institute for Advanced Study


Surfraw gets its configuration from three sources, in order:

  1. Environment variables
  2. /etc/surfraw.conf
  3. $HOME/.surfraw.conf

/etc/surfraw.conf and $HOME/.surfraw.conf are both fragments of bourne-shell style shell script.

/etc/surfraw.conf should use def and defyn to define variables. These functions set variables unless they are already set by the environment. defyn is used for boolean configuration variables, def for all others. For instance:

 def     SURFRAW_text_browser	/usr/bin/lynx
 defyn   SURFRAW_graphical		no

$HOME/.surfraw.conf should use sh-style entries, eg:


This is because you want them to override environment variables unconditionally.

Configuration Variables

Variable Meaning Default
SURFRAW_global_conf Location of global configuration file. /etc/surfraw.conf
SURFRAW_conf Location of per-user configuration file. $HOME/.surfraw.conf
SURFRAW_graphical Whether to use a graphical browser. no
SURFRAW_text_browser Name/path of text browser executable.
e.g. links, lynx, w3m
SURFRAW_graphical_browser Name/path of graphical browser executable.
e.g mozilla, netscape etc.
SURFRAW_text_browser_args Text browser arguments, or "none". none
SURFRAW_graphical_browser_args Graphical browser arguments, or "none". none
SURFRAW_graphical_remote Whether to use -remote openURL for graphical browser. yes
SURFRAW_new_window When using SURFRAW_graphical_remote, open a new window? no
SURFRAW_screen Name of screen command to run. screen
SURFRAW_screen_args Arguments to screen command
SURFRAW_new_screen If surfraw is running under screen(1), start a new screen for each text browser invocation? no
SURFRAW_quiet I can't enjoy it with you talking all the time. no
SURFRAW_quote_args Whether to "quote" all the arguments. no
SURFRAW_quote_ifs Whether to re-quote arguments if they have spaces in, ie so:
sr google foo "bar baz" bam
works as expected.
SURFRAW_results Default number of results to return (not supported by all elvi). 30
SURFRAW_escape_url_args Whether to escape [%"$%&+,/:;<=>?@[\^{|}~'] characters in command line arguments subsequently used to construct a url. yes
SURFRAW_lang Elvi supporting this will use it to select a default country or language. It should be set to an ISO 2-letter country code (e.g. uk, de, ca). none
SURFRAW_customsearch_provider Provider for searches that use a search engine. Supported: google, duckduckgo. duckduckgo


Location of the elvi.
Default system wide configuration file.
Default per-user config file
System wide bookmarks file.
Per-user bookmarks file.

Development and Support

Surfraw was originally written by Julian Assange. It is now maintained and improved by a team of programmers based around the surfraw-devel mailing list.

The surfraw project webpage is at surfraw.alioth.debian.org

To report a bug or request an enhancement (e.g. a new elvi), send email to surfraw-devel@lists.alioth.debian.org

The current development version of surfraw can be obtained from the surfraw git repository. To check out the repository:

git clone git://anonscm.debian.org/surfraw/surfraw.git

Interested in contributing? Subscribe to surfraw-devel. View the surfraw-devel list archives. Read the surfraw HACKING guide. Surfrawize the soul of your favourite internet wonder. Join the Shell Users' Revolutionary Front Against the WWW by submitting code. Reclaim heathen lands. Bear witness to the truth. Its love will set you free.

Last modified: Mon Feb 5 06:26:15 NZDT 2018