golazo

README

Golazo

A minimalist terminal user interface (TUI) for following football (soccer) matches in real-time. Get live match updates, finished match statistics, and minute-by-minute events directly in your terminal.

Golazo also ships a JSON CLI for agents and scripts (golazo live, finished, match, leagues, capabilities) — see CLI / Agent Mode.

Golazo was created for those moments when you can't stream or watch matches live. It gives you a handy, non-intrusive, and minimalist way to keep up with your favourite football leagues.

Perfect for developers and terminal enthusiasts who want match updates without leaving their workflow.

[!NOTE] If you enjoy Golazo, give it a star and share it with your friends. That helps others find it and keeps the project going!

Quick Install: brew install 0xjuanma/tap/golazo · Other options

Features

• Live Match Tracking: Timeline & Real-time updates for goals, cards, and substitutions with automatic polling
• Finished Matches: View results from today, last 3 days, or last 5 days
• Match Statistics & Details: Possession, shots, passes, standings, formations with player ratings, and more in focused dialogs
• Official Highlights & Replay Links: Clickable links for official highlights and instant goal replays
• Goal Notifications: Desktop notifications for goals as they happen
• 65+ Leagues: Organized by region (Europe, Americas, Global) with tab navigation in Settings
• JSON CLI for agents: golazo live, finished, match, leagues, capabilities — structured output, typed error codes, exit code map. See docs/CLI.md.

Installation & Update

Self-update: Run golazo --update anytime to get the latest version.

Homebrew

# Install
brew install 0xjuanma/tap/golazo

# Update
brew upgrade 0xjuanma/tap/golazo

Install script

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/0xjuanma/golazo/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/0xjuanma/golazo/main/scripts/install.ps1 | iex

Build from source

git clone https://github.com/0xjuanma/golazo.git
cd golazo
go build 
./golazo

Usage

Run the application:

golazo

Navigation: ↑/↓ or j/k to move, Enter to select, / to filter, Tab to focus view, Esc to go back, q to quit.

CLI / Agent Mode

For scripts and agentic tools (Claude Code, Codex, MCP servers), Golazo exposes JSON subcommands:

golazo capabilities | jq .                       # self-discover the contract
golazo live                                       # live matches right now
golazo finished --include-upcoming                # today's full slate
golazo finished --days 3                          # last 3 days
golazo match 2001 --mock                          # full match details (best-effort against real IDs; reliable with --mock)
golazo leagues --all                              # every supported league

Full contract — JSON envelope, error codes, exit codes, retry policy, schema, jq recipes — in docs/CLI.md.

Docs

• Supported Leagues: Full list of available leagues and competitions, customize your preferences in the Settings menu.
• Notifications: Desktop notification setup and configuration
• CLI / Agent Mode: JSON subcommands for agents and scripts (golazo live, finished, match, leagues)

---

Built with Bubble Tea, Lip Gloss & Bubbles by Charm

Author: @0xjuanma