Brokli 🥦

A fast, concurrent broken link checker for websites and sitemaps

Brokli (a play on "broken links") is a CLI tool that helps developers validate all links on a page or sitemap during development. It checks HTTP status codes concurrently and displays results with color-coded output, making it easy to spot broken links before deployment.

Features

• 🚀 Concurrent Checking - Uses worker pools to check multiple links simultaneously (default: 10 workers)
• 🎨 Color-Coded Output - Green for success, red for errors, cyan for redirects
• 📊 Progress Indication - Real-time progress counter shows checking status
• 🎯 Smart Filtering - Shows only broken links by default to reduce noise
• 🔍 Verbose Mode - Optional flag to display all links with their status codes
• 🔄 GitHub Actions Integration - Native support with workflow annotations and step outputs
• ⚙️ Configurable - Adjust workers, timeouts, redirects, and user agent
• 🌐 Sitemap Support - Check entire sitemaps with metadata display
• 🧪 Well Tested - 94%+ test coverage with comprehensive test suite

Installation

Download Binary

The easiest way to install Brokli is to download a pre-built binary from the GitHub Releases page.

Linux / macOS:

# Download the latest release for your platform
# Replace VERSION, OS, and ARCH with appropriate values
# Example: brokli_0.1.0_linux_amd64.tar.gz

# Extract the archive
tar -xzf brokli_VERSION_OS_ARCH.tar.gz

# Move to your PATH
sudo mv brokli /usr/local/bin/

# Verify installation
brokli --version

Windows:

Download the .zip file for Windows from the releases page, extract it, and add the brokli.exe to your PATH.

From Source

# Clone the repository
git clone https://github.com/EndlessTrax/brokli.git
cd brokli

# Build the binary
go build -o brokli .

# Optionally, move to your PATH
sudo mv brokli /usr/local/bin/

Usage

Check a Single Page

Check all links on a webpage and show only broken ones:

brokli check url https://example.com

Output:

Found 10 links
Checking links... 10/10

✓ All links are working!

Check with Verbose Output

Show all links with their status codes:

brokli check url https://example.com --output-format=verbose
# or use the short flag
brokli check url https://example.com -o verbose
# backward compatible with the old -v flag
brokli check url https://example.com -v

Output:

Found 10 links
Checking links... 10/10

All Links:
✓ 1. [200] Home -> https://example.com
✓ 2. [200] About -> https://example.com/about
→ 3. [301] Old Page -> https://example.com/redirect
✗ 4. [404] Missing -> https://example.com/missing

Summary: 1 broken link found out of 10 total

Output Formats

Brokli supports multiple output formats via the --output-format (or -o) flag:

• default - Shows only broken links with color-coded status (default behavior)
• verbose - Shows all links with their status codes
• github - GitHub Actions compatible format with workflow annotations and step outputs

Examples:

# Default format (broken links only)
brokli check url https://example.com

# Verbose format (all links)
brokli check url https://example.com -o verbose

# GitHub Actions format
brokli check url https://example.com -o github

Check a Sitemap

Check all URLs in a sitemap:

brokli check sitemap https://example.com/sitemap.xml

Output:

Found 70 URLs in sitemap
Checking URLs... 70/70

Broken URLs:
✗ 1. [404] https://example.com/old-page (modified: 2023-09-24T00:00:00+00:00)
✗ 2. [404] https://example.com/removed (modified: 2024-01-15T00:00:00+00:00)

Summary: 2 broken URLs found out of 70 total

GitHub Actions Integration

Use Brokli in GitHub Actions CI/CD workflows with the --output-format=github flag:

brokli check url https://example.com --output-format=github
brokli check sitemap https://example.com/sitemap.xml --output-format=github
# Or use the short form
brokli check url https://example.com -o github

This formats output specifically for GitHub Actions:

• Workflow Annotations: Broken links appear as errors in the GitHub Actions UI
• Step Outputs: Summary statistics are written to GITHUB_OUTPUT for use in downstream steps
• Exit Code: Standard exit codes for CI integration

Example GitHub Actions Workflow:

name: Check Links
on: [push, pull_request]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Brokli
        run: |
          curl -L https://github.com/EndlessTrax/brokli/releases/latest/download/brokli_linux_amd64.tar.gz | tar xz
          sudo mv brokli /usr/local/bin/
      
      - name: Check site links
        id: check
        run: brokli check url https://yoursite.com --output-format=github
        continue-on-error: true
      
      - name: Check results
        run: |
          echo "Total links: ${{ steps.check.outputs.total_links_count }}"
          echo "Broken links: ${{ steps.check.outputs.broken_links_count }}"
          if [ "${{ steps.check.outputs.has_broken_links }}" == "true" ]; then
            echo "⚠️ Broken links found!"
            exit 1
          fi

Step Outputs Available:

• broken_links_count - Number of broken links found
• total_links_count - Total number of links checked
• has_broken_links - Boolean (true/false) indicating if any broken links were found

Status Code Colors

• 🟢 Green [200] - Success (2xx status codes)
• 🔵 Cyan [301] - Redirects (3xx status codes)
• 🔴 Red [404] - Client errors (4xx status codes)
• 🔴 Bold Red [500] - Server errors (5xx status codes)
• 🟡 Yellow [-1] - Unchecked/errors

Use Cases

Local Development

Validate links on your local dev server before pushing:

brokli check url https://localhost:3000
brokli check sitemap https://localhost:3000/sitemap.xml

Pre-Deployment Checks

Quick validation before deploying to production:

# Check staging site
brokli check sitemap https://staging.example.com/sitemap.xml -v

CI/CD Integration

Automate link checking in your GitHub Actions workflow:

# In GitHub Actions workflow
brokli check url https://example.com --output-format=github

See the GitHub Actions Integration section for complete workflow examples.

Roadmap

Planned Features

• Configuration File Support - .brokli.yml for persistent settings
• Link Caching - Cache results to avoid re-checking unchanged links
• Export Formats - Output results to JSON, CSV, or Markdown
• Multi-Sitemap Processing - Check multiple sitemaps concurrently

Development

Prerequisites

• Go 1.24.0 or higher
• Task (optional, for running tasks)

Running Tests

Run all unit tests:

task test
# or
go test ./...

Run tests with coverage:

task test-coverage
# or
go test -v -race -coverprofile=coverage.out ./...

Code Quality

Formatting

Format all Go code:

task fmt
# or
go fmt ./...

Check formatting without making changes:

gofmt -s -l .

Linting

Lint code using golangci-lint:

task ci-lint
# or
golangci-lint run ./...

Running All CI Checks Locally

Before pushing, run all CI checks:

task ci

This runs:

1. Tests with race detection
2. Format check
3. Linting

Building

Build the project:

task build
# or
go build -o brokli .

This creates a brokli binary in the current directory.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Development workflow and branch naming conventions
• Coding standards and architecture patterns
• Testing guidelines
• Pull request process
• Commit message conventions

License

This project is licensed under the MIT License - see the LICENSE file for details.