lychee

https://lychee.cli.rs
Admin
lychee is an async, Rust-powered command-line tool designed to quickly catch broken links in...
Tokens:25,122
Snippets:407
Trust Score:6.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install lychee with Snap

Source: https://lychee.cli.rs/guides/getting-started

Install lychee using the snap package manager.

```bash
sudo snap install lychee
```

--------------------------------

### Full configuration example

Source: https://lychee.cli.rs/guides/config

A comprehensive example configuration file demonstrating all available options.

```toml
#############################  Display  #############################


# Verbose program output
# Accepts log level: "error", "warn", "info", "debug", "trace"
verbose = "info"


# Output format
format = "detailed"


# Output display mode
mode = "emoji"


# Don't show interactive progress bar while checking links.
no_progress = false


# Path to summary output file.
output = ".config.dummy.report.md"


# Show host statistics
host_stats = true


# Extract links instead of checking them
dump = true


# Dump inputs instead of doing link extraction / checking
dump_inputs = true


#############################  Cache  ###############################


# Enable link caching. This can be helpful to avoid checking the same links on
# multiple runs.
cache = true


# Discard all cached requests older than this duration.
max_cache_age = "2d"


# A list of status codes that will be ignored from the cache
cache_exclude_status = "500.."


#############################  Runtime  #############################


# File to read and write cookies
cookie_jar = "cookie-jar"


# Number of threads to utilize.
# Defaults to number of cores available to the system if omitted.
threads = 2


# Maximum number of allowed redirects.
max_redirects = 10


# Maximum number of allowed retries before a link is declared dead.
max_retries = 2


# Maximum number of concurrent link checks.
max_concurrency = 14


# extension applied to files without extension
default_extension = "md"


# GitHub API token
github_token = "secret"


# Resolve directories to index files
index_files = ["index.html"]


# Preprocess input files
preprocess = { command = "preprocess.sh" }


#############################  Requests  ############################


# User agent to send with each request.
user_agent = "curl/7.83. 1"


# Website timeout from connect to response finished.
timeout = 20


# Minimum wait time in seconds between retries of failed requests.
retry_wait_time = 2


# Comma-separated list of accepted status codes for valid links.
# Supported values are:
#
# accept = ["200..=204", "429"]
# accept = "200..=204, 429"
# accept = ["200", "429"]
# accept = "200, 429"
accept = ["200", "429"]


# Proceed for server connections considered insecure (invalid TLS).
insecure = false


# Only test links with the given schemes (e.g. https).
# Omit to check links with any other scheme.
# At the moment, we support http, https, file, and mailto.
scheme = ["https"]


# When links are available using HTTPS, treat HTTP links as errors.
require_https = false


# Request method
method = "get"


# Custom request headers
header = { "accept" = "text/html", "x-custom-header" = "value" }


# Remap URI matching pattern to different URI.
remap = ["https://example.com http://example.invalid"]


# Fallback extensions to apply when a URL does not specify one.
# This is common in documentation tools that cross-reference files without extensions.
fallback_extensions = ["md", "html"]


# Base URL or website root directory to check relative URLs.
base_url = "https://example.com"


# Root path to use when checking absolute local links, must be an absolute path
root_dir = "/dist"


# HTTP basic auth support. This will be the username and password passed to the
# authorization HTTP header. See
# <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
basic_auth = ["example.com user:pwd"]


# Enable the checking of fragments in links, both anchor fragments and text fragments.
# See <https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments>
include_fragments = "full"


# Minimum accepted TLS Version
min_tls = "TLSv1_3"


#############################  Exclusions  ##########################


# Skip missing input files (default is to error if they don't exist).
skip_missing = false


# Do not skip hidden directories and files
hidden = true


# Do not skip files that are ignored
no_ignore = true


# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
# blocks.
include_verbatim = false


# Ignore case of paths when matching glob patterns.
glob_ignore_case = false
```

--------------------------------

### Compile and install lychee with Cargo

Source: https://lychee.cli.rs/guides/getting-started

Build and install lychee from source using Cargo.

```bash
cargo install lychee
```

--------------------------------

### Install lychee with WinGet

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on Windows using the WinGet package manager.

```bash
winget install lycheeverse.lychee
```

--------------------------------

### Install build dependencies for Linux

Source: https://lychee.cli.rs/guides/getting-started

Install the Rust toolchain and required system libraries on APT-based Linux distributions.

```bash
curl -sSf '<https://sh.rustup.rs>' | sh
apt install gcc pkg-config libc6-dev libssl-dev
```

--------------------------------

### Install lychee with Homebrew

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on macOS or Linux using Homebrew.

```bash
brew install lychee
```

--------------------------------

### Basic remap configuration

Source: https://lychee.cli.rs/recipes/local-folder

An example of a basic remap that applies to any URL beginning with the specified string.

```bash
--remap "^https://example\.com/docs file://$(pwd)/out"
```

--------------------------------

### Install lychee with Scoop

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on Windows using the Scoop package manager.

```bash
scoop install lychee
```

--------------------------------

### Install lychee with Chocolatey

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on Windows using the Chocolatey package manager.

```bash
choco install lychee
```

--------------------------------

### Install lychee with zypper

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on OpenSUSE using the zypper package manager.

```bash
zypper in lychee
```

--------------------------------

### Install lychee with FreeBSD pkg

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on FreeBSD using the pkg manager.

```bash
pkg install lychee
```

--------------------------------

### Install lychee with Nix

Source: https://lychee.cli.rs/guides/getting-started

Run lychee using nix-shell.

```bash
nix-shell -p lychee
```

--------------------------------

### Example HTML with future URL

Source: https://lychee.cli.rs/recipes/local-folder

An example of an HTML file containing a permalink that points to a URL that does not exist yet.

```html
<h1>My blog post</h1>
<a href="https://example.com/docs/2025-01-01-post.html">Permalink</a>
```

--------------------------------

### Run Lychee with --preprocess flag

Source: https://lychee.cli.rs/guides/preprocessing

Example command to invoke a preprocessing script for a set of files.

```bash
lychee files/* --preprocess ./preprocess.sh
```

--------------------------------

### Basic link check with lychee_lib::check

Source: https://lychee.cli.rs/guides/library

A simple 'hello world' example demonstrating how to check a URL using the default lychee_lib::check function.

```rust
use lychee_lib::Result;


#[tokio::main]
async fn main() -> Result<()> {
  let response = lychee_lib::check("https://github.com/lycheeverse/lychee").await?;
  println!("{response}");
  Ok(())
}
```

--------------------------------

### Example preprocess.sh helper script

Source: https://lychee.cli.rs/guides/preprocessing

A bash script that handles different file extensions by converting them to a readable format for Lychee.

```bash
#!/usr/bin/env bash


case "$1" in
*.pdf)
    exec pdftohtml -i -s -stdout "$1"
    # Alternatives:
    # exec pdftotext "$1" -
    # exec pdftk "$1" output - uncompress | grep -aPo '/URI *\(\K[^)]*'
    ;;
*.odt|*.docx|*.epub|*.ipynb)
    exec pandoc "$1" --to=html --wrap=none --markdown-headings=atx
    ;;
*.odp|*.pptx|*.ods|*.xlsx)
    # libreoffice can't print to stdout unfortunately
    libreoffice --headless --convert-to html "$1" --outdir /tmp
    file=$(basename "$1")
    file="/tmp/${file%.*}.html"
    sed '/<body/,$!d' "$file" # discard content before body which contains libreoffice URLs
    rm "$file"
;;
*.adoc|*.asciidoc)
    asciidoctor -a stylesheet! "$1" -o -
    ;;
*.csv)
    # specify --delimiter if values not delimited by ","
    exec csvtk csv2json "$1"
    ;;
*)
    # identity function, output input without changes
    exec cat
    ;;
esac
```

--------------------------------

### Absolute path links in HTML

Source: https://lychee.cli.rs/recipes/root-dir

Example of HTML links starting with '/' that require --root-dir for resolution.

```html
<!-- index.html -->
<a href="/about.html">About</a>
<a href="/docs/guide.html">Guide</a>
```

--------------------------------

### Install lychee with pacman

Source: https://lychee.cli.rs/guides/getting-started

Install lychee on Arch Linux using the pacman package manager.

```bash
pacman -S lychee
```

--------------------------------

### Documentation site absolute links

Source: https://lychee.cli.rs/recipes/root-dir

Example of absolute paths used in documentation site files.

```html
<!-- docs/index.html -->
<a href="/api/v1.html">API</a>
<a href="/guide/start.html">Get Started</a>
```

--------------------------------

### Example HTML relative links

Source: https://lychee.cli.rs/recipes/base-url

A sample of relative links that require a base URL to resolve correctly when deployed.

```html
<a href="./getting-started.html">Get Started</a>
<a href="../about.html">About Us</a>
```

--------------------------------

### Repeat CLI options

Source: https://lychee.cli.rs/guides/cli

Example of using the --exclude flag multiple times to ignore specific URLs.

```bash
lychee --exclude https://example.com --exclude https://example.org README.md
```

--------------------------------

### Full URL matching examples

Source: https://lychee.cli.rs/recipes/excluding-links

Demonstrates that regex matches the full URL including the scheme, which is critical for correct filtering.

```bash
# This will work:
lychee --exclude '^https://www\.linkedin\.com'


# This might not work as expected:
lychee --exclude 'linkedin\.com'
```

--------------------------------

### Configure retries via CLI

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example command to set the maximum number of retries to 5 and the initial wait time to 3 seconds.

```bash
lychee --max-retries 5 --retry-wait-time 3 https://example.com
```

--------------------------------

### Configure retries in lychee.toml

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example configuration file settings to set the maximum number of retries to 5 and the initial wait time to 3 seconds.

```toml
max_retries = 5
retry_wait_time = 3
```

--------------------------------

### Set request method

Source: https://lychee.cli.rs/guides/cli

Sets the HTTP request method. The default is get.

```bash
lychee --method <METHOD>
```

--------------------------------

### Basic link exclusion patterns

Source: https://lychee.cli.rs/recipes/excluding-links

Examples of using --exclude and --include flags to filter links by domain or pattern.

```bash
# Exclude all links that contain "example.com" and "example.org"
lychee --exclude example\.com --exclude example\.org


# Same as above, but using a single exclude parameter
lychee --exclude example\.(com|org)


# Check only links that contain "twitter.com"
lychee --exclude '.*' --include 'twitter\.com'
```

--------------------------------

### Advanced link exclusion scenarios

Source: https://lychee.cli.rs/recipes/excluding-links

Real-world examples for excluding specific file types, social media, or URL parameters.

```bash
# Exclude links to specific file types
lychee --exclude '\.(pdf|zip|png|jpg)$'


# Exclude links to social media platforms
lychee --exclude '(facebook|twitter|linkedin|instagram)\.com'


# Check only links within your own domain
lychee --include '^https?://yourdomain\.com'


# Exclude links to specific subdomains
lychee --exclude '^https?://blog\.example\.com'


# Exclude links with certain URL parameters
lychee --exclude '\?utm_source='


# Exclude links to specific sections of a website
lychee --exclude 'example\.com/blog/\d{4}/'
```

--------------------------------

### Override configuration option

Source: https://lychee.cli.rs/guides/config

Example of overriding the default timeout value in the configuration file.

```toml
timeout = 30
```

--------------------------------

### Configure GitLab CI job for link checking

Source: https://lychee.cli.rs/continuous-integration/gitlab

This job installs lychee, runs it against TEST.md, and exports the results as a JUnit XML artifact for visualization in GitLab.

```yaml
Check links:
  stage: test
  script:
    - apt-get update -qq && apt-get install -y -qq wget
    # recommended to pin a stable version such as "lychee-v0.24.0"
    - version="nightly"
    - wget -qO- "https://github.com/lycheeverse/lychee/releases/download/$version/lychee-x86_64-unknown-linux-gnu.tar.gz" | tar --strip-components=1 -xz
    - ./lychee --verbose --include-mail --format junit --output results.xml TEST.md
  artifacts:
    when: always
    reports:
      junit: results.xml
```

--------------------------------

### Check Wikilinks CLI Command

Source: https://lychee.cli.rs/recipes/md-wikilinks

A starting command to check for the existence of files used by Wikilinks, requiring the inclusion flag, base directory, and fallback extensions.

```bash
lychee --include-wikilinks \
--base-url /path/to/your/local/directory \
--fallback-extensions md,mdx .
```

--------------------------------

### Map Remote Domain to Local Folder

Source: https://lychee.cli.rs/recipes/local-folder

Maps URLs starting with a specific domain to a local directory using the --root-dir and --remap flags.

```bash
lychee ./out --root-dir ./out --remap "^https://docs\.example\.com file://$(pwd)/out"
```

--------------------------------

### Configure basic authentication

Source: https://lychee.cli.rs/guides/cli

Provide credentials for basic authentication in the format 'http://example.com username:password'.

```bash
lychee --basic-auth <BASIC_AUTH>
```

--------------------------------

### -h, --help flag

Source: https://lychee.cli.rs/guides/cli

Prints the help documentation.

```bash
lychee --help
```

--------------------------------

### Specify configuration file

Source: https://lychee.cli.rs/guides/cli

Use a custom configuration file. Multiple files can be specified, with later ones taking precedence.

```bash
lychee --config <FILE_PATH>
```

--------------------------------

### Custom client check with ClientBuilder

Source: https://lychee.cli.rs/guides/library

Demonstrates how to build a custom client using ClientBuilder to perform link checks.

```rust
use lychee_lib::{ClientBuilder, Result, Status};


#[tokio::main]
async fn main() -> Result<()> {
  let client = ClientBuilder::default().client()?;
  let response = client.check("https://github.com/lycheeverse/lychee").await?;
  assert!(response.status().is_success());
  Ok(())
}
```

--------------------------------

### Create Temporary Root Directory Structure

Source: https://lychee.cli.rs/recipes/local-folder

Sets up a temporary root directory with a symbolic link to mimic the remote website structure for complex cases.

```text
├── out
│   └── page.html
└── temp-root-dir
    └── docs -> ../out
```

```bash
mkdir temp-root-dir
ln -s ../out temp-root-dir/docs
```

--------------------------------

### Proceed with insecure connections

Source: https://lychee.cli.rs/guides/cli

Use -i or --insecure to allow connections with invalid TLS certificates.

```bash
lychee --insecure[=<false|true>]
```

--------------------------------

### Check documentation sites locally

Source: https://lychee.cli.rs/recipes/base-url

Command to check links against a local development server.

```bash
lychee --base-url http://localhost:3000/docs/ "docs/**/*.html"
```

--------------------------------

### Network error: Forbidden

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example of a network error indicating a 403 Forbidden status.

```text
Network error: Forbidden
```

--------------------------------

### Configuring ClientBuilder options

Source: https://lychee.cli.rs/guides/library

Shows the various configuration options available when building a custom client, such as timeouts, user agents, and custom headers.

```rust
let client = lychee_lib::ClientBuilder::builder()
    .includes(includes)
    .excludes(excludes)
    .max_redirects(cfg.max_redirects)
    .user_agent(cfg.user_agent)
    .allow_insecure(cfg.insecure)
    .custom_headers(headers)
    .method(method)
    .timeout(timeout)
    .github_token(cfg.github_token)
    .scheme(cfg.scheme)
    .accepted(accepted)
    .build()
    .client()?;
```

--------------------------------

### Example of Too Many Redirects Error

Source: https://lychee.cli.rs/troubleshooting/redirects

The error message displayed when lychee encounters an excessive number of redirects.

```text
Failed: Too many redirects: error following redirect for url
```

--------------------------------

### Network error: Connection reset

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example of a network error indicating the server forcibly closed the connection.

```text
Network error: Connection reset by server. Server forcibly closed connection
```

--------------------------------

### Remap domain in sitemap

Source: https://lychee.cli.rs/recipes/migration

Checks links in a sitemap after migrating from example.com to example.org.

```bash
lychee --remap 'example.com example.org' -- https://example.com/sitemap.xml
```

--------------------------------

### Disable retries via CLI

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example command to disable retries entirely by setting the maximum retries to 0.

```bash
lychee --max-retries 0 https://example.com
```

--------------------------------

### Network error: Request failure

Source: https://lychee.cli.rs/troubleshooting/network-errors

Example of a generic network error message indicating a failure to send a request.

```text
Failed: Network error: error sending request for url
```

--------------------------------

### Check documentation site links

Source: https://lychee.cli.rs/recipes/root-dir

Command to check documentation links from the project root.

```bash
# Assuming you're in the project root
lychee --root-dir . "docs/**/*.html"
```

--------------------------------

### Check local curl user agent

Source: https://lychee.cli.rs/troubleshooting/network-errors

Retrieve the current user agent string used by your local curl installation.

```bash
curl -s https://httpbin.org/user-agent
```

--------------------------------

### Check local files with file:// base URL

Source: https://lychee.cli.rs/recipes/base-url

Use a file:// URL with the --base-url flag to verify links on your local filesystem without needing a running server.

```bash
lychee --base-url file:///absolute/path/to/site/ "**/*.html"
```

--------------------------------

### Print version

Source: https://lychee.cli.rs/guides/cli

Displays the current version of the Lychee CLI.

```bash
lychee --version
```

--------------------------------

### GitHub Rate Limit Error Message

Source: https://lychee.cli.rs/troubleshooting/rate-limits

Example of the error message displayed when GitHub rate limits are encountered due to a missing token.

```text
GitHub token not specified. To check GitHub links reliably, use `--github-token`
flag / `GITHUB_TOKEN` env var.
```

--------------------------------

### Check links with --base-url

Source: https://lychee.cli.rs/recipes/base-url

Command to verify links by specifying the base URL where the site will be hosted.

```bash
lychee --base-url https://example.com/docs/ "**/*.html"
```

--------------------------------

### Wikilink Renaming Syntax

Source: https://lychee.cli.rs/recipes/md-wikilinks

Examples of Wikilinks using the pipe character to specify alternative titles, which Lychee resolves by stripping the title and using the filename.

```markdown
[[Filename|Alternative Title]]
[[Filename|Another Alternative Title]]
```

--------------------------------

### Verify links before deployment

Source: https://lychee.cli.rs/recipes/base-url

Command to verify links against a production base URL before deploying.

```bash
lychee --base-url https://example.com/docs/ "docs/**/*.html"
```

--------------------------------

### Enable caching in Docker

Source: https://lychee.cli.rs/recipes/caching

Create a .lycheecache file locally and mount it as a volume in the Docker container to persist cache data between runs.

```bash
touch .lycheecache
docker run -it -v $(pwd)/.lycheecache:/.lycheecache lycheeverse/lychee --cache --verbose https://lychee.cli.rs
```

--------------------------------

### Specify custom configuration file

Source: https://lychee.cli.rs/guides/config

Use the --config flag to point to a specific TOML configuration file.

```bash
lychee --config config.toml
```

--------------------------------

### Run lychee in Docker

Source: https://lychee.cli.rs/guides/getting-started

Execute lychee in a Docker container by mounting the local directory. The --init flag allows terminal interruption, and -it enables the interactive progress bar.

```bash
docker run --init -it -v `pwd`:/input lycheeverse/lychee /input/README.md
```

--------------------------------

### Configure general operational settings

Source: https://lychee.cli.rs/guides/config

Settings for input file sources, output generation, web archiving, and link suggestion features.

```toml
files_from = "fixtures/empty-file.txt"


# Generate special output instead of performing link checking
generate = "man"


# Use the Wayback Machine as web archive
archive = "wayback"


# Search and suggest link replacements for all broken links
suggest = true
```

--------------------------------

### Set web archive for suggestions

Source: https://lychee.cli.rs/guides/cli

Specify the web archive service to use for link suggestions.

```bash
lychee --archive <ARCHIVE>
```

--------------------------------

### Configure fallback extensions with --fallback-extensions

Source: https://lychee.cli.rs/recipes/pretty-urls

Use this option to resolve local links missing an extension by appending .html or .htm to the filename.

```bash
# If a local link does not resolve to an existing file, lychee will attempt to
# find a file by appending `.html` or `.htm`, in that order.
lychee --fallback-extensions html,htm
```

--------------------------------

### Show host statistics

Source: https://lychee.cli.rs/guides/cli

Enable --host-stats to display per-host statistics at the end of the run.

```bash
lychee --host-stats[=<false|true>]
```

--------------------------------

### Remap to local development server

Source: https://lychee.cli.rs/recipes/migration

Redirects domain links to a local development environment.

```bash
lychee --remap 'example.com localhost:8000' ...
```

--------------------------------

### Set a custom user agent

Source: https://lychee.cli.rs/troubleshooting/network-errors

Attempt to bypass website blocks by mimicking a common user agent like curl.

```bash
lychee --user-agent "curl/8.4.0" https://example.com
```

--------------------------------

### Set system limits with launchctl

Source: https://lychee.cli.rs/troubleshooting/open-files

Use launchctl to apply a permanent increase to file limits on macOS systems.

```bash
sudo launchctl limit maxfiles 4096 unlimited
```

--------------------------------

### Configure IP and network settings

Source: https://lychee.cli.rs/guides/config

Settings for handling private IP ranges, mail addresses, WikiLinks, and network request behavior.

```toml
exclude_all_private = false


# Exclude private IP address ranges from checking.
exclude_private = false


# Exclude link-local IP address range from checking.
exclude_link_local = false


# Exclude loopback IP address range and localhost from checking.
exclude_loopback = false


# Check mail addresses
include_mail = true


# Check WikiLinks in Markdown files
include_wikilinks = true


# Only check local files
offline = true


# Accept timed out requests
accept_timeouts = true
```

--------------------------------

### Configure host-specific settings

Source: https://lychee.cli.rs/guides/config

Set global host concurrency and request intervals, or define overrides for specific hosts.

```toml
host_concurrency = 5


# Minimum interval between requests to the same host
host_request_interval = "50ms"


# Customize hosts
[hosts."blog.example.com"]
# Overwrite `host_concurrency` for this host
concurrency = 5
# Overwrite `host_request_interval` for this host
request_interval = "0" # zero disables rate limiting
# Merge global `header` values with the following `headers` for this host
headers = { "A" = "B" }
```

--------------------------------

### Check blogging platform links

Source: https://lychee.cli.rs/recipes/base-url

Command to check links for blogs hosted on platforms like WordPress, Ghost, or Jekyll.

```bash
lychee --base-url https://example.com/blog/ "content/**/*.html"
```

--------------------------------

### Configure file extensions and inclusions

Source: https://lychee.cli.rs/guides/config

Specify file extensions to check and define regex patterns for URLs that should always be included.

```toml
extensions = ["md","txt","html"]


# URLs to check (supports regex). Has preference over all excludes.
include = ['gist\.github\.com.*']
```

--------------------------------

### Preprocess input files

Source: https://lychee.cli.rs/guides/cli

Executes a command for each input file and processes its standard output instead of the original file content. A wrapper script can be used to handle multiple file types or custom arguments.

```bash
lychee --preprocess <COMMAND>
```

```bash
#!/usr/bin/env bash
case "$1" in
*.pdf)
    exec pdftohtml -i -s -stdout "$1"
    ;;
*.odt|*.docx|*.epub|*.ipynb)
    exec pandoc "$1" --to=html --wrap=none
    ;;
*)
    # identity function, output input without changes
    exec cat
    ;;
esac
```

--------------------------------

### Enable caching on the command line

Source: https://lychee.cli.rs/recipes/caching

Use the --cache flag to save results to a .lycheecache file. Subsequent runs with this flag will utilize the cached data.

```bash
lychee --cache --verbose --no-progress './**/*.md' './**/*.html'
```

--------------------------------

### Static site directory structure

Source: https://lychee.cli.rs/recipes/root-dir

Typical directory structure for a static site builder project.

```text
my-site/
├── public/           # Generated files live here
│   ├── about.html
│   └── docs/
│       └── guide.html
└── content/          # Source files
    └── index.md
```

--------------------------------

### Check static site links

Source: https://lychee.cli.rs/recipes/root-dir

Command to check links in a generated public directory.

```bash
lychee --root-dir public "public/**/*.html"
```

--------------------------------

### Basic lychee usage

Source: https://lychee.cli.rs/guides/cli

The standard command structure for running the lychee link checker.

```bash
lychee [OPTIONS] [inputs]...
```

--------------------------------

### Check links with --root-dir

Source: https://lychee.cli.rs/recipes/root-dir

Command to check absolute links by specifying the public directory as the root.

```bash
lychee --root-dir ./public "**/*.html"
```

--------------------------------

### Enable request caching

Source: https://lychee.cli.rs/guides/cli

Enable disk-based caching for requests using the .lycheecache file.

```bash
lychee --cache[=<false|true>]
```

--------------------------------

### Use --cookie-jar to persist cookies

Source: https://lychee.cli.rs/recipes/cookies

Pass the --cookie-jar flag with a path to a JSON file to load and store cookies. If the file does not exist, lychee will create it.

```bash
lychee --cookie-jar cookies.json https://example.com
```

--------------------------------

### Debug file existence

Source: https://lychee.cli.rs/recipes/root-dir

Use ls to verify that files exist at the expected paths.

```bash
# Example debugging steps
ls -la ./public/about.html
ls -la ./public/docs/guide.html
```

--------------------------------

### Configure base URL with and without trailing slash

Source: https://lychee.cli.rs/recipes/base-url

Demonstrates the difference between a correct directory-based base URL with a trailing slash and an incorrect version that treats the path as a file.

```bash
# ✅ Good - links will resolve correctly
lychee --base-url https://example.com/docs/
# ❌ Bad - links will break
lychee --base-url https://example.com/docs
```

--------------------------------

### Include verbatim sections

Source: https://lychee.cli.rs/guides/cli

Use --include-verbatim to find links within pre and code blocks.

```bash
lychee --include-verbatim[=<false|true>]
```

--------------------------------

### --extensions flag

Source: https://lychee.cli.rs/guides/cli

Specifies a comma-separated list of file extensions to process; files not matching these are skipped.

```bash
lychee --extensions <EXTENSIONS>
```

--------------------------------

### Check GitHub Pages sites

Source: https://lychee.cli.rs/recipes/base-url

Commands for checking links on GitHub Pages for both project sites and local development environments.

```bash
# For a project site
lychee --base-url https://username.github.io/project/ "**/*.html"


# For local development
lychee --base-url http://localhost:4000/project/ "**/*.html"
```

--------------------------------

### Remap using regular expressions

Source: https://lychee.cli.rs/recipes/migration

Uses regex to migrate links from GitHub to GitLab while preserving the path.

```bash
lychee --remap 'github.com/(.*) gitlab.com/$1' ...
```

--------------------------------

### Basic link checker workflow

Source: https://lychee.cli.rs/continuous-integration/github

A basic workflow that runs lychee on push events to check all repository links.

```yaml
name: Links


on:
  push:


jobs:
  linkChecker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Link Checker
        id: lychee
        uses: lycheeverse/lychee-action@v2
        with:
          format: "markdown"
          args: ". --verbose"
```

--------------------------------

### Configure index files with --index-files

Source: https://lychee.cli.rs/recipes/pretty-urls

Use this option to resolve directory links by checking for specific index files within the directory.

```bash
# If a local link resolves to a directory, lychee will attempt to find one of
# the listed index files within the directory, in the order given.
lychee --index-files index.html,index.htm
```

--------------------------------

### Enable anchor link checking with --include-fragments

Source: https://lychee.cli.rs/recipes/anchors

Use the --include-fragments flag to enable validation of internal anchor links for a given URL or file.

```bash
lychee --include-fragments 'https://example.com/docs'
```

--------------------------------

### Check All Links On A Website

Source: https://lychee.cli.rs/guides/getting-started

Checks all links on a specific website. This command is not recursive and only checks the provided page.

```bash
lychee https://example.com
```

--------------------------------

### Remap with concurrency limits and exclusions

Source: https://lychee.cli.rs/recipes/migration

Combines remapping with exclusions and concurrency limits to avoid server overload.

```bash
lychee --remap 'example.com example.org' \
       --exclude 'example.org/old' \
       --exclude 'oldmail@example.com' \
       --verbose \
       --no-progress \
       --max-concurrency 4 \
       https://example.com/sitemap.xml
```

--------------------------------

### Link conversion with --base-url

Source: https://lychee.cli.rs/recipes/base-url

Shows how relative links are transformed into absolute URLs when the --base-url flag is applied.

```html
<!-- Original links -->
<a href="./guide.php">Guide</a>
<a href="../about.php">About</a>
<a href="https://example.com">Absolute</a>


<!-- After --base-url https://example.com/docs/ -->


<a href="https://example.com/docs/guide.php">Guide</a>
<a href="https://example.com/about.php">About</a>
<a href="https://example.com">Absolute</a>
```

--------------------------------

### Enable Verbose Mode to Trace Redirects

Source: https://lychee.cli.rs/troubleshooting/redirects

Use the -vvv flag to inspect the redirect chain and identify patterns in the URLs being followed.

```bash
echo 'https://example.com' | lychee -vvv
[DEBUG] Redirecting to https://example.com/foo
[DEBUG] Redirecting to https://example.com/bar
[DEBUG] Redirecting to https://example.com/baz
✗ [ERR] https://example.com | Failed: Too many redirects: error following redirect for url


Issues found in 1 input. Find details below.
```

--------------------------------

### -f, --format flag

Source: https://lychee.cli.rs/guides/cli

Sets the output format for the final status report. Defaults to 'compact'.

```bash
lychee --format <FORMAT>
```

--------------------------------

### Specify inputs for link checking

Source: https://lychee.cli.rs/guides/cli

Define the files, globs, or URLs to be checked for broken links.

```bash
lychee [inputs]...
```

--------------------------------

### Run Lychee with Complex Subfolder Mapping

Source: https://lychee.cli.rs/recipes/local-folder

Executes lychee using a temporary root directory and multiple remap rules to handle subfolder-based website structures.

```bash
lychee ./out \
  --root-dir ./temp-root-dir \
  --remap "^https://example\.com/docs file://$(pwd)/out" \
  --remap "file://$(pwd)/temp-root-dir/docs file://$(pwd)/temp-root-dir/docs" \
  --remap "file://$(pwd)/temp-root-dir https://example\.com"
```

--------------------------------

### Debug path resolution with --verbose

Source: https://lychee.cli.rs/recipes/root-dir

Use the --verbose flag to see how lychee resolves paths.

```bash
lychee --root-dir "$(pwd)/public" --verbose "**/*.html"
```

--------------------------------

### Pull lychee Docker image

Source: https://lychee.cli.rs/guides/getting-started

Download the official lychee Docker image.

```bash
docker pull lycheeverse/lychee
```

--------------------------------

### --fallback-extensions flag

Source: https://lychee.cli.rs/guides/cli

Attempts to locate missing file:// URIs by trying specified fallback extensions in order.

```bash
lychee --fallback-extensions <FALLBACK_EXTENSIONS>
```

--------------------------------

### Use cookie jar

Source: https://lychee.cli.rs/guides/cli

Read and write cookies to a specified file to be sent with requests.

```bash
lychee --cookie-jar <COOKIE_JAR>
```

--------------------------------

### Exclude paths using the configuration file

Source: https://lychee.cli.rs/recipes/excluding-paths

Use the exclude_path key in your configuration file to define a list of regex patterns for paths to skip.

```toml
exclude_path = [
    "\\.txt$",      # skip .txt extensions
    "(^|/)test/",   # skip directories named "test"
    "[aeiouAEIOU]", # exclude paths containing vowels
]
```

--------------------------------

### Specify output file

Source: https://lychee.cli.rs/guides/cli

Defines the file path where the status report will be saved.

```bash
lychee --output <OUTPUT>
```

--------------------------------

### --files-from flag

Source: https://lychee.cli.rs/guides/cli

Reads input filenames from a specified file or stdin.

```bash
lychee --files-from <PATH>
```

```bash
lychee --files-from list.txt
find . -name '*.md' | lychee --files-from -
echo 'README.md' | lychee --files-from -
```

--------------------------------

### Include WikiLinks

Source: https://lychee.cli.rs/guides/cli

Use --include-wikilinks to check WikiLinks in Markdown files. Requires --base-url to be specified.

```bash
lychee --include-wikilinks[=<false|true>]
```

--------------------------------

### Set user agent

Source: https://lychee.cli.rs/guides/cli

Sets the user agent string for requests. The default is lychee/x.y.z.

```bash
lychee --user-agent <USER_AGENT>
```

--------------------------------

### Suggest link replacements

Source: https://lychee.cli.rs/guides/cli

Suggests replacements for broken links using a web archive. The archive can be specified with --archive.

```bash
lychee --suggest[=<false|true>]
```

--------------------------------

### Check Links From Stdin

Source: https://lychee.cli.rs/guides/getting-started

Pipes links directly into lychee via stdin instead of using a file.

```bash
cat test.md | lychee -
echo 'https://example.com' | lychee -
```

--------------------------------

### --dump-inputs flag

Source: https://lychee.cli.rs/guides/cli

Dumps all input sources from which links would be collected instead of performing extraction or checking.

```bash
lychee --dump-inputs[=<false|true>]
```

--------------------------------

### --github-token flag

Source: https://lychee.cli.rs/guides/cli

Provides a GitHub API token to avoid rate limiting when checking github.com links.

```bash
lychee --github-token <GITHUB_TOKEN>
```
Tokens:
Raw