Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



89 Commits

Repository files navigation

PyPI Python versions License Build status


sp is a command line utility to search from the terminal.

It is inspired by the projects ddgr and googler.

Table of contents


$ pip install spcli


Command Line

$ sp -h
usage: [-h] [-d] [-f] [-s SITE] [-t SPAN] [-u] [-v] [-np]
             [--browser BROWSER] [--json] [--no-color]
             [keywords [keywords ...]]

Search from the terminal.

positional arguments:
  keywords              search keywords

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           enable debug logging
  -f, --first           open the first result in a web browser
  -s SITE, --site SITE  search a site
  -t SPAN, --time SPAN  time limit search to 1 d|w|m|y (day,week,month,year)
  -u, --unsafe          disable the family filter
  -v, --version         show program's version number and exit
  -np, --no-prompt      do not enter interactive mode
  --browser BROWSER     open results using this web browser
  --json                output the results in JSON; implies --no-prompt
  --no-color            disable color output

Version 1.0.4
Copyright © 2018 Gary Blackwood <>
License: GPLv3

Interactive Mode

f          view the first set of results
n          view the next set of results
p          view the previous set of results
[index]    open search result in web browser
c [index]  copy the search result link to the clipboard
s KEYWORDS perform a search for KEYWORDS
?          show help
q          exit
*          all other inputs are treated as new search keywords


  1. Search for terms.
$ sp hello world
  1. Search for news about brexit:
$ sp -s brexit
  1. Search for results from the past 24 hours.
$ sp -t d barcelona fc
  1. Open the first result automatically
$ sp -f python docs
  1. Disable safe search.
$ sp -u pawn
  1. Output in JSON format.
$ sp --json climate change papers

Browser Support

If the BROWSER environment variable exists, it will be used to open search results. If not, sp will attempt to use one from the this list.

You can specify which browser to use using the --browser flag. This also accepts a path to the browser executable.

$ sp --browser firefox


The requests library is used to perform the HTTP requests. You can configure proxies by setting the environment variables HTTP_PROXY and HTTPS_PROXY.

$ export HTTP_PROXY=""
$ export HTTPS_PROXY=""

Development Quick Start

Create and activate a virtual environment.

$ mkvirtualenv -p python3 sp
$ workon sp

Install the dependencies.

$ pip install -r requirements.txt

Format the code.

$ black sp/*.py

Run static analysis on the code.

$ pylint sp/*.py
$ flake8 sp/*.py


Please create an issue for any problems that you encounter.

  1. Disable the coloured output if it does not work correctly on your system:
$ sp --no-color