Google Command Line Interface
Version 0.3
Released under the GNU GPL v2 or later

01 November 2005
**************************************


What is gcli?
-------------

gcli is a command line interface to Google, using the Google
web search API.  This program provides two things: 

1) the 'gcli' script --

   'gcli' can be used to script Google searches or as an 
   interactive shell to Google's search data 

2) the 'libgcli' library --

   a pure Python library for developing Python programs
   around Google's web search API


Install
-------

gcli requires SOAPpy (a Python module which requires fpconst).
For complete installation details, see the INSTALL file.

For the impatient:  

From the unpacked gcli source directory, as root run:

  $ python setup.py install


Configure
---------

In order to use gcli, you need to have a developer's key 
from Google.  Go to http://www.google.com/apis/download.html
to register for a key.  Once you have a key, create a .gcli 
directory in your home directory.  Place the key in ~/.gcli 
as a text file named "key".  This key file should only 
contain your Google developer's key.

If you would like to store your key somewhere other than your
gcli directory, you can set the KEYPATH option in a config
file in the .gcli user directory.  For example,

		## Sample ~/.gcli/config 
		KEYPATH = /path/to/keyfile

Note: gcli still assumes the key file will be called "key", 
only found at the location specified in the config, not in
the ~/.gcli directory itself. 

If you will be using particular search parameters often,
you can customize gcli's default settings in ~/.gcli/config.
See the example config file in the examples directory of the gcli
source.


The Script
----------

If run with no arguments, gcli will enter an interactive
prompt.  At the prompt, type "help" for more info.

Here are some examples on using gcli from the command line.

The following will search Google for the word deryck.

		$ gcli deryck

To return up to 50 results for the same query (not the default 10):

		$ gcli -m 50 deryck

To print only urls from the above query:

		$ gcli -d url -m 50 deryck

To filter duplicate pages:

		$ gcli -d url -m 50 -f deryck

To turn on safe searching:

		$ gcli -d url -m 50 -fs deryck

To pass a multiple word query:

		$ gcli -d url 'deryck hodge'

Phrases must be signaled by quotes within quotes:

		$ gcli -d url 'deryck hodge "google development"'

The above would search for the words "deryck" and "hodge"
and the phrase "google development".  Google searches are
case insensitive, whether using gcli or the Google website.

Certain of Google's special search syntaxes may be used:

		$ gcli -d url "deryck intitle:about"


The Library
-----------

To use the libgcli library to build other programs, you 
primarily need the Params and Results objects.

An example (from the interactive Python prompt):

>>> from libgcli.params import Params
>>> from libgcli.query import Results
>>>
>>> p = Params()
>>> p.query = 'samba development'
>>> r = Results(p)

To now get a list of resultsElements:

>>> r.results()

You can also do your own printing loop, (note that
each result element is a list of 10 hits),

>>> for result in r.results():
...     for hit in result:
...             print hit.URL

Or you can use the display lib:

>>> from libgcli.display import Display
>>> Display('url', r.results())