Skip to content

⚽ Football scores for hackers. 💻 A command line interface for all the football scores.


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Soccer CLI

PyPI version Join the chat at Run on

Soccer for Hackers - a CLI for all the football scores.


An API key from will be required and you can register for one here.

Build from source

$ git clone
$ cd soccer-cli
$ python install

You can set the API key using an environment variable as shown above or create a file .soccer-cli.ini in your home folder (/home/username/.soccer-cli.ini) that contains only your API token, such that:

$ cat /home/username/.soccer-cli.ini


Currently supports Linux, Mac OS X, NetBSD, FreeBSD and Windows.

To get colorized terminal output on Windows, make sure to install ansicon and colorama.


Get standings for a league

$ soccer --standings --league=PL # PL is the league code for English Premier League

Get scores for a particular team

$ soccer --team=MUFC # MUFC is the team code for Manchester United
$ soccer --team=PSG --time=10 # scores for all the Paris Saint-Germain games over the past 10 days

Get upcoming fixtures

$ soccer --time 5 --upcoming # get upcoming fixtures for next 5 days
$ soccer --time 5 --upcoming --use12hour # upcoming fixture for next 5 days with timings in 12 hour format

Get scores for live games

$ soccer --live

Get scores for a particular league

$ soccer --league=BL # BL is the league code for Bundesliga
$ soccer --league=FL --time=15 # get scores for all the French Ligue games over the past 15 days

Get information about players of a team

$ soccer --team=JUVE --players

Get scores for all seven leagues with a set time period

$ soccer --time=10 # get scores for all the seven leagues over the past 10 days

Get the output in csv or json

$ soccer --league PL --standings --csv # prints the output in csv format
$ soccer --league PL --standings --json # prints the output in json format

Store the ouput in a file

$ soccer --league PL --standings --csv -o 'standings.csv' # stores the ouput in csv format in `standings.csv`


$ soccer --help

List of supported leagues and their league codes

  • World:
    • WC: World Cup (if running/active)
  • Europe:
    • CL: Champions League
    • EC: European Championships (if running/active)
  • Brazil:
    • BSA: Brazil Serie A
  • England:
    • PL: English Premier League
    • ELC: English Championship
  • France:
    • FL1: Ligue 1
  • Germany:
    • BL: Bundesliga
  • Italy:
    • SA: Serie A
  • Netherlands:
    • DED: Eredivisie
  • Portugal:
    • PPL: Primeira Liga
  • Spain:
    • LLIGA: La Liga

Team and team codes

For a full list of supported team and team codes see this.


To run testing suite from root of repo

$ python -m unittest discover tests

To run specific test file (in this case the tests in

$ python -m unittest tests.test_request_handler




Live scores

Team scores

Output in json format


  • Enable cache.
  • Add more test cases.
  • Add fixtures for UEFA Champions League.
  • Add league filter for live scores.
  • Color coding for Europa league and differentiation between straight CL and CL playoff spots, and the same for EL spots.
  • Add support for team line up.
  • A built in watch feature so you can run once with --live and just leave the program running.
  • Python 3 support.


Open sourced under MIT License


If you like my work, please support the project by donating.


⚽ Football scores for hackers. 💻 A command line interface for all the football scores.







No packages published