footstats-cli 0.1.0

Football Stats Scraper - Footstats CLI

Footstats CLI

Football player stats, transfers, and market values — straight from your terminal.

---

Overview

Footstats is an open-source CLI tool that lets you search for any football player and retrieve their profile, transfer history, and match statistics — all from your terminal, powered by data from Transfermarkt.

---

Features

• Player Search — Search any player by name
• Player Profile — Market value, age, club, position, nationality, and more
• Transfer History — Full transfer history with fees and market values
• Match Stats — Per-game stats including goals, assists, cards, minutes, passes, and shots
• Interactive Menu — Navigate with a single keypress
• Direct Commands — Call any command directly with arguments

---

Data Sources

Source	Data
Transfermarkt	Market value, transfers, match stats, player profile

---

Requirements

• Python 3.13+
• UV package manager

---

Installation

1. Install UV

# macOS
brew install uv

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository

git clone https://github.com/Marin2409/footstats-cli.git
cd footstats-scraper

3. Install dependencies

uv sync

4. Set up environment variables

cp .env.example .env

5. Activate the Virtual Environment

# Get Python interpreter path for VSCode
uv run which python

Using VSCODE Command Pallete:

1. Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
2. Type "Python: Select Interpreter"
3. Paste the path from above
4. Create a new terminal (Cmd+Shift+P -> "Create New Terminal with Profile")

In terminal Activate the new virtual environment so that any Python command you run or package you install uses it.

source .venv/bin/activate

Every time you install a new package in that environment, activate the environment again.

This makes sure that if you use a terminal (CLI) program installed by that package, you use the one from your virtual environment and not any other that could be installed globally, probably with a different version than what you need.

6. Install the CLI

uv pip install -e .

---

Usage

Interactive menu

footstats

Direct commands

footstats player "Cristiano Ronaldo"
footstats transfer-history "Lionel Messi"
footstats stats "Erling Haaland"

Options

footstats --help
footstats --version

---

Configuration

Copy .env.example to .env and adjust as needed:

USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
ACCEPT_LANGUAGE=en-US,en;q=0.5
ACCEPT_ENCODING=gzip, deflate
REQUEST_DELAY=3.0   # seconds between requests — increase if getting blocked

---

Project Structure

footstats-scraper/
├── src/
│   ├── cli/
│   │   ├── main.py          # CLI entry point
│   │   └── utils/           # Display helpers
│   ├── models/              # Dataclasses
│   ├── providers/           # Scraping logic
│   └── utils/               # Config, parsing, requests
├── tests/
├── .env.example
├── pyproject.toml
└── README.md

---

Development

Run with Python:

# Run directly with python without installing
python -m src.cli.main [command] [argument]

Run with UV:

# Run directly with uv without installing
uv run python -m src.cli.main [command] [arguments]

"scr"	"cli"	"main"	"command"	"argument"
Root	Parent Folder	File you wanna run	Action	Passing argument, Ex. "cristiano"

Run Tests

# Run tests
pytest tests/test_providers.py ..

---

Disclaimer

This project is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by Transfermarkt or any other data provider. Use it at your own risk and ensure compliance with their Terms of Service and avoid excessive requests. Please respect The REQUEST_DELAY setting in .env helps ensure responsible usage.

Users are solely responsible for ensuring that their use of this software complies with applicable laws, regulations, website terms of service, robots.txt policies, and rate-limiting requirements.

The authors provide this software for educational and research purposes only and make no representations regarding the legality or appropriateness of its use in any particular jurisdiction or against any particular website.

---

User Responsibility

By using this software, you acknowledge that you are responsible for determining whether your use complies with applicable laws, regulations, and the terms of service of any websites you access.

The authors are not responsible for how users choose to use this software.

---

Contributing

Contributions are welcome! Please open an issue before submitting a pull request so we can discuss the change.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

---

License

MIT License — see LICENSE for details.