How to use the command 'lychee' (with examples)

Lychee is a powerful command-line tool designed to identify broken URLs swiftly and efficiently. Whether you’re managing a large website, auditing content for a company, or ensuring that all hyperlinks in your project documentation are functional, lychee makes it possible to automate the traditionally labor-intensive process of checking URL validity.

Use case 1: Scan a website for broken links

Code:

lychee https://example.com

Motivation:

Webmasters and content creators often face the challenge of maintaining a robust website with numerous pages and outbound links. Over time, some of these links may become inactive or broken due to external site changes or page removals. Using lychee to scan a website for broken links ensures the integrity of your site, contributing to a favorable user experience and improving SEO rankings by preserving link equity.

Explanation:

• lychee: The command to invoke the lychee tool.
• https://example.com: The URL of the website you wish to scan for broken links.

Example output:

🦜 Checking https://example.com...
[200] https://www.some-valid-link.com
[404] https://www.some-broken-link.com (broken)
[301] https://www.redirected-link.com (redirected to https://www.new-link.com)

Use case 2: Display a breakdown of error types

Code:

lychee --format detailed https://example.com

Motivation:

For those who require a granular understanding of why specific links are failing, using the --format detailed option provides an in-depth error analysis. This can be critical when diagnosing complex issues related to link redirection loops or authentication-required URLs, allowing developers or administrators to pinpoint problems accurately and devise appropriate solutions.

Explanation:

• lychee: The command to invoke the lychee tool.
• --format detailed: A flag to output a detailed breakdown of errors.
• https://example.com: The URL of the website you are scanning.

Example output:

🦜 Checking https://example.com...
Detailed Report:
[200] https://working-link.com
[404] https://missing-link.com (Not Found)
[403] https://protected-link.com (Forbidden - access denied)
[500] https://server-error.com (Internal Server Error)

Use case 3: Limit the amount of connections to prevent DDOS protection

Code:

lychee --max-concurrency 5 links.txt

Motivation:

When scanning a large number of URLs, either on a robust server or a smaller set of webpages, there’s always a risk of triggering DDOS protection mechanisms that perceive too many simultaneous HTTP requests as malicious. By limiting concurrency, lychee can be gentler on servers, respecting rate limits and reducing false-positive security alerts.

Explanation:

• lychee: The command to invoke the lychee tool.
• --max-concurrency 5: An argument that limits the number of simultaneous HTTP requests to five.
• links.txt: A text file containing a list of URLs to be checked.

Example output:

🦜 Checking links from links.txt with max concurrency set to 5...
[200] http://example.com/page1
[200] http://example.com/page2
[404] http://example.com/page3 (broken)

Use case 4: Check files in a directory structure for any broken URLs

Code:

grep -r "pattern" | lychee -

Motivation:

Projects with complex directory structures often embed URLs across various files like HTML, Markdown, or plain text files. Automatically verifying these URLs helps in ensuring all embedded links are reliable, especially during a final quality check before deployment or publication. This command is essential for developers working on documentation-heavy projects or static site generators.

Explanation:

• grep -r "pattern": The grep command searches recursively in files for a specific pattern and outputs the matches.
• |: A pipeline operator that passes the output of one command as input to another.
• lychee -: Using lychee to process input from a standard input stream (- signifies this).

Example output:

🦜 Checking URLs provided via standard input...
[200] https://functioning-url.com
[404] https://missing-url.com (broken)

Use case 5: Display help

Code:

lychee --help

Motivation:

Understanding all available options of a command and its appropriate usage is crucial for both beginners and seasoned users alike. The --help option provides a comprehensive guide to lychee’s capabilities, ensuring users can leverage its full potential effectively.

Explanation:

• lychee: The command to invoke the lychee tool.
• --help: A flag to display help information about lychee, including available commands and their descriptions.

Example output:

lychee 0.6.0
...
USAGE:
    lychee [URL] [OPTIONS]
...
OPTIONS:
    --help                Print help information
    --format <FORMAT>     Specifies the output format (default, detailed)
    --max-concurrency     Maximum number of concurrent network connections
...

Conclusion:

Lychee is an invaluable tool for anyone responsible for maintaining and ensuring the link health of a website or digital content. By applying these use cases, users can effectively identify issues, prevent negative impacts on user experience, and uphold the quality and reliability of their digital properties.