speedtest-cli
=============

Command line interface for testing internet bandwidth using
speedtest.net

.. image:: https://pypip.in/v/speedtest-cli/badge.png
        :target: https://pypi.python.org/pypi/speedtest-cli/
        :alt: Latest Version
.. image:: https://pypip.in/d/speedtest-cli/badge.png
        :target: https://pypi.python.org/pypi/speedtest-cli/
        :alt: Downloads
.. image:: https://pypip.in/license/speedtest-cli/badge.png
        :target: https://pypi.python.org/pypi/speedtest-cli/
        :alt: License

Versions
--------

speedtest-cli works with Python 2.4-3.4

Installation
------------

pip / easy\_install
~~~~~~~~~~~~~~~~~~~

::

    pip install speedtest-cli

or

::

    easy_install speedtest-cli

Github
~~~~~~

::

    pip install git+https://github.com/sivel/speedtest-cli.git

or

::

    git clone https://github.com/sivel/speedtest-cli.git
    python speedtest-cli/setup.py install

Just download (Like the way it used to be)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    wget -O speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest_cli.py
    chmod +x speedtest-cli

or

::

    curl -Lo speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest_cli.py
    chmod +x speedtest-cli

Usage
-----

::

    $ speedtest-cli -h
    usage: speedtest_cli.py [-h] [--bytes] [--share] [--simple] [--list]
                            [--server SERVER] [--mini MINI] [--source SOURCE]
                            [--timeout TIMEOUT] [--secure] [--callback CALLBACK]
                            [--callback-help] [--version]

    Command line interface for testing internet bandwidth using speedtest.net.
    --------------------------------------------------------------------------
    https://github.com/sivel/speedtest-cli

    optional arguments:
      -h, --help           show this help message and exit
      --bytes              Display values in bytes instead of bits. Does not
                           affect the image generated by --share
      --share              Generate and provide a URL to the speedtest.net share
                           results image
      --simple             Suppress verbose output, only show basic information
      --list               Display a list of speedtest.net servers sorted by
                           distance
      --server SERVER      Specify a server ID to test against
      --mini MINI          URL of the Speedtest Mini server
      --source SOURCE      Source IP address to bind to
      --timeout TIMEOUT    HTTP timeout in seconds. Default 10
      --secure             Use HTTPS instead of HTTP when communicating with
                           speedtest.net operated servers
      --callback CALLBACK  Script to run at certain stages of operation
      --callback-help      Show help about --callback
      --version            Show the version number and exit

::

    $ speedtest-cli --callback-help

    speedtest-cli callback script help
    ----------------------------------

    If a callback script is given via --callback, that script will be run
    during operation.  The value passed to --callback may be the path to
    a script or a shell fragment which will be passed to the shell.

    The environment of the callback script is the same as the environment
    of speedtest-cli plus variables starting with 'STC_' that have information
    about the current state of the program.  Each execution of the callback
    script will retain all the previous 'STC_' variables and possibly add new
    variables.

    Following are the points at which the callback script will be executed and
    what 'STC_' enviornment variables will be available (only new or changed
    variables will be listed for each state):

    pre_ping - run before gathering ping time results
        STC_STATE - set to 'pre_ping'
        STC_UNITS - units used for the DL and UL speeds, e.g. Mbit/s

    post_ping
        STC_STATE   - set to 'post_ping'
        STC_PING_MS - the calculated ping latency in milliseconds

    pre_download
        STC_STATE   - set to 'pre_download'

    post_download
        STC_STATE        - set to 'post_download'
        STC_DL_SPEED     - calculated speed in STC_UNITS units
        STC_DL_SPEED_RAW - calculated speed in bits/sec

    pre_upload
        STC_STATE - set to 'pre_upload'

    post_upload
        STC_STATE        - set to 'post_upload'
        STC_UL_SPEED     - calculated speed in STC_UNITS units
        STC_UL_SPEED_RAW - calculated speed in bits/sec

    examples:
      # show all STC_ variables set during each callback
      speedtest-cli --callback --simple 'echo "$STC_STATE:"; env | grep "^STC_" | sort; echo'

      # only take action when the post_upload state is reached
      speedtest_cli --callback 'test $STC_STATE = 'post_upload' && env | grep "^STC_.*SPEED"'


Inconsistency
-------------

It is not a goal of this application to be a reliable latency reporting tool.

Latency reported by this tool should not be relied on as a value indicative of ICMP
style latency. It is a relative value used for determining the lowest latency server
for performing the actual speed test against.

There is the potential for this tool to report results inconsistent with Speedtest.net.
There are several concepts to be aware of that factor into the potential inconsistency:

1. Speedtest.net has migrated to using pure socket tests instead of HTTP based tests
2. This application is written in Python
3. Different versions of Python will execute certain parts of the code faster than others
4. CPU and Memory capacity and speed will play a large part in inconsistency between
   Speedtest.net and even other machines on the same network

Issues relating to inconsistencies will be closed as wontfix and without
additional reason or context.