SURFRAW(1)

SURFRAW(1) from the General Commands Manual — yes bestie, section 1, and it's entirely about surfraw. Settle in, this one's a whole personality. 💖

---

✨ NAME ✨

surfraw — a fast unix command line interface to WWW services. That's it. Short, sweet, iconic. 💅

🎀 SYNOPSIS 🎀

surfraw elviname [options] search words ...
sr elviname [options] search words ...
sr -elvi
sr [options] bookmark [search words]

🌸 DESCRIPTION 🌸

Okay so here's the whole vibe: Surfraw gives you a fast unix command line interface to a whole bunch of popular WWW search engines and other artifacts of power. It straight-up reclaims google, altavista, dejanews, freshmeat, research index, slashdot and many others from the false-prophet, pox-infested heathen lands of html-forms, and plants these wonders right where they belong — deep in unix heartland, as god loving extensions to the shell. periodt. 👑

Surfraw is a collection of elvi, and each one knows how to search one specific web site. Wanna see the list of elvi? Type:

surfraw -elvi

Heads up: sr is an alias for surfraw, so this does literally the exact same thing:

sr -elvi

To search using an elvis (that's the manual's word, not mine, and yeah they mean an elvi 💀) you go:

sr elviname [options] search terms..

Like, say you wanna search google for info on Debian ports, using the "I'm feeling lucky" option:

sr google -l debian ports

🦋 Adding the elvi to your path

If you're a regular user of surfraw, you're gonna get sick of typing sr or surfraw every single time, ngl. You can get the old behaviour back — running the elvi directly — by adding the elvi directory (/usr/lib/surfraw) to your path, either manually or with surfraw-update-path(1). ✨

🍓 Bookmarks

Surfraw supports bookmarks, bestie. To add one, add it to /etc/xdg/surfraw/bookmarks or $HOME/.config/surfraw/bookmarks.

The bookmarks file format is simple: each bookmark lives on its own separate line, with the bookmark and URL separated by whitespace, eg:

ntk   http://www.ntk.net/

If the url contains the string %s, you can specify an optional argument to the bookmark. Without an argument, only the domain will be returned. With arguments, %s will be replaced by the arguments. This obviates the need to create elvi for sites with very simple search options. no cap.

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/xdg/surfraw/bookmarks. 🌈

---

🔥 OPTIONS 🔥

Use sr elviname -local-help for elvi-specific options.

The following options work with all elvi:

• -help — Show summary of options (including elvi-specific options).
• -local-help — Show elvi-specific options.
• -version — Show version of program.
• -browser=EXECUTABLE — Set browser (default: sensible-browser).
• -elvi — Display a list of other Surfraw mechanisms for conquering evil. 😈
• -escape-url-args=yes|no — Apply url escaping to arguments (default: yes)
• -q, -quote — Bracket all arguments with " characters (default: no). 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.

💜 EXAMPLES 💜

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

🧚 CONFIGURATION 🧚

Surfraw uses the XDG basedir spec (http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html) to locate config files. The default locations are shown below, but they can be modified by setting the environment variables $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS. See the spec for more details.

Surfraw gets its configuration from three sources, in order:

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

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

/etc/xdg/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/.config/surfraw/conf should use sh-style entries, eg:

SURFRAW_text_browser=/usr/bin/lynx
SURFRAW_graphical=no

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

👑 CONFIGURATION VARIABLES 👑

• SURFRAW_global_conf — Location of global configuration file. Default:

def SURFRAW_global_conf /etc/xdg/surfraw/conf

• SURFRAW_conf — Location of per-user configuration file. Default:

def SURFRAW_conf $HOME/.config/surfraw/conf

• SURFRAW_graphical — Whether to use a graphical browser. Default:

defyn SURFRAW_graphical no

• SURFRAW_text_browser — Name/path of text browser executable. e.g. links, lynx, w3m Default:

def SURFRAW_text_browser sensible-browser

• SURFRAW_graphical_browser — Name/path of graphical browser executable. e.g mozilla, netscape etc. Default:

def SURFRAW_graphical_browser sensible-browser

• SURFRAW_text_browser_args — Text browser arguments, or "none". Default:

def SURFRAW_text_browser_args none

• SURFRAW_graphical_browser_args — Graphical browser arguments, or "none". Default:

def SURFRAW_graphical_browser_args none

• SURFRAW_graphical_remote — Whether to use "-remote openURL" for graphical browser. Default:

defyn SURFRAW_graphical_remote yes

• SURFRAW_new_window — When using SURFRAW_graphical_remote, open a new window? Default:

defyn SURFRAW_new_window no

• SURFRAW_screen — Name of screen command to run. Default:

def SURFRAW_screen screen

• SURFRAW_new_screen — If surfraw is running under screen(1), start a new screen for each text browser invocation? Default:

defyn SURFRAW_new_screen no

• SURFRAW_screen_args — Arguments to pass to the SURFRAW_screen command Default:

def SURFRAW_screen_args ""

• SURFRAW_quote_args — Whether to "quote" all the arguments. Default:

defyn SURFRAW_quote_args 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. Default:

defyn SURFRAW_quote_ifs    yes

• SURFRAW_results — Default number of results to return (not supported by all elvi). Default:

def SURFRAW_results 30

• SURFRAW_escape_url_args — Whether to escape [% "$%&+,/:;<=>?@[{|}~'] characters in command line arguments subsequently used to construct a url. Default:

defyn SURFRAW_escape_url_args yes

🦋 FILES 🦋

• /usr/lib/surfraw — Location of the elvi.
• ${HOME}/.config/surfraw/elvi — Per-user elvi.
• /etc/xdg/surfraw/conf — Default system wide configuration file.
• $HOME/.config/surfraw/conf — Default per-user config file
• /etc/xdg/surfraw/bookmarks — System wide bookmarks file.
• $HOME/.config/surfraw/bookmarks — Per-user bookmarks file.

💀 BUGS 💀

Please report any bugs found (or any web sites in need of surfrawizing) either via the debian bug tracking system (http://bugs.debian.org/) or to the surfraw-devel list (surfraw-devel@lists.alioth.debian.org).

⭐ SEE ALSO ⭐

http://alioth.debian.org/projects/surfraw/

🫶 PROPAGANDA 🫶

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

Read HACKING. 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. 🌈✨

Join us on surfraw-devel@lists.alioth.debian.org

💖 AUTHORS 💖

Originally written by Julian Assange.

Now maintained by the surfraw-devel team <surfraw-devel@lists.alioth.debian.org>.

See the file AUTHORS for the full list of contributors.

Man page by Ian Beckwith, based on the original README and an earlier man page by Christian Surchi.

🌟 COPYRIGHT 🌟

  Copyright (c) 2003-2018 The Surfraw-Devel Team
                           <surfraw-devel@lists.alioth.debian.org>
  Copyright (c) 2000-2001 Julian Assange <proff@iq.org>
  Copyright (c) 2001 Australian Institute for Collaborative Research
  Copyright (c) 2000 Melbourne Institute for Advanced Study

The copyright holders listed above assert no rights on this release of the software ``surfraw'' and thereby explicity place this release into the into the public domain. Do what you will. 💅

---

That's the whole page, bestie. This one's from the surfraw source, dated Feb 03, 2004, and it's SURFRAW(1) all the way down. Go surf something. 🦋💖