deadlink-checker-cli

Find broken links in websites and markdown files — zero dependencies, CI-friendly.

Features

• Crawl websites and check every link on the page
• Check all links in a markdown file ([text](url), <url>)
• Recursively check all .md files in a directory
• Colored output: red for BROKEN, green for OK
• Follows redirects (up to 3 hops)
• HEAD-first requests with GET fallback
• Concurrent link checking (configurable, default 5)
• URL caching — never checks the same URL twice
• Skips mailto:, tel:, #anchor links automatically
• Exit code 1 when broken links found (CI-friendly)
• Zero external dependencies — uses Node.js built-ins only

Install

npm install -g deadlink-checker-cli
# or use without installing:
npx deadlink-checker-cli <target>

Usage

# Check all links on a website
deadlink https://example.com

# Crawl 2 levels deep
deadlink https://example.com --depth 2

# Check links in a markdown file
deadlink README.md

# Custom timeout (ms)
deadlink README.md --timeout 5000

# Check all .md files in a directory
deadlink --dir ./docs

# Show OK links too
deadlink README.md --verbose

# Adjust concurrency
deadlink https://example.com --concurrency 10

Output

deadlink-checker-cli v1.0.0

Checking file: /path/to/README.md
  BROKEN https://old.example.com/gone (HTTP 404)
  ERROR  https://dead.example.com (Timeout)
  BROKEN https://moved.example.com/page (HTTP 410)

──────────────────────────────────────────────────
Summary:
  OK:      12
  Broken:  3
  Skipped: 2 (mailto:, tel:, #anchors, etc.)
  Total checked: 15
──────────────────────────────────────────────────

FAILED — 3 broken link(s) found.

Options

| Flag | Short | Default | Description | |------|-------|---------|-------------| | --depth | -d | 1 | Crawl depth for website URLs | | --timeout | -t | 10000 | Request timeout in milliseconds | | --concurrency | -c | 5 | Max concurrent requests | | --verbose | -v | off | Show OK links in output | | --help | -h | — | Show help |

Exit Codes

| Code | Meaning | |------|---------| | 0 | All links OK | | 1 | One or more broken links found | | 2 | CLI usage error (file not found, etc.) |

GitHub Actions

name: Check Broken Links

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 8 * * 1'  # Every Monday

jobs:
  deadlinks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check broken links in docs
        run: npx deadlink-checker-cli --dir ./docs

      - name: Check README
        run: npx deadlink-checker-cli README.md

Use Cases

• Pre-commit hook to catch broken links before merging
• Weekly scheduled CI to detect link rot
• Validate documentation before publishing
• SEO audits — detect dead outbound links

License

MIT © Wilson Xu