Skip to main content
Linkspector provides several command-line options to customize how links are checked and how results are displayed.

​
Available Options

​
-c, --config
string
Specify a custom configuration file path.Default: .linkspector.ymlExample:
linkspector check --config path/to/config.yml
linkspector check -c .linkspector.prod.yml
Use this when:
  • You have multiple environments (dev, staging, production)
  • Your config file is in a non-standard location
  • You want to test different configurations without modifying your main config
​
-j, --json
boolean
Output the results in JSON format (Reviewdog Diagnostic Format).Default: falseExample:
linkspector check --json
linkspector check -j > results.json
The JSON output follows the Reviewdog Diagnostic Format (RDJSON) specification, making it easy to integrate with CI/CD pipelines and code review tools.Note: Cannot be used with --showstat.Example output structure:
{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "ERROR",
  "diagnostics": [
    {
      "message": "Cannot reach https://example.com Status: 404",
      "location": {
        "path": "docs/page.md",
        "range": {
          "start": { "line": 10, "column": 5 },
          "end": { "line": 10, "column": 35 }
        }
      },
      "severity": "ERROR"
    }
  ]
}
​
-s, --showstat
boolean
Display detailed statistics about the links checked.Default: falseExample:
linkspector check --showstat
linkspector check -s
Shows a formatted table with:
  • Total files checked
  • Total links checked
  • Breakdown by link type (HTTP, file, email)
  • Count of working vs failed links
Note: Cannot be used with --json.Example output:
💀📊 Linkspector check stats
┌───────────────────────────────┬────────┐
│ 🟰 Total files checked        │     12 │
├───────────────────────────────┼────────┤
│ 🔗 Total links checked        │    156 │
├───────────────────────────────┼────────┤
│ 🌐 Hyperlinks                 │     89 │
├───────────────────────────────┼────────┤
│ 📁 File and header links      │     62 │
├───────────────────────────────┼────────┤
│ ✉️  Email links (Skipped)      │      5 │
├───────────────────────────────┼────────┤
│ ✅ Working links              │    154 │
├───────────────────────────────┼────────┤
│ 🚫 Failed links               │      2 │
└───────────────────────────────┴────────┘

​
Option Combinations

​
Valid Combinations

You can combine compatible options: 
# Custom config with statistics
linkspector check --config custom.yml --showstat

# Custom config with JSON output
linkspector check -c custom.yml -j

# Just the config option
linkspector check --config .linkspector.prod.yml

​
Incompatible Options

The --json and --showstat options cannot be used together. If you try to combine them, Linkspector will exit with an error: 
linkspector check --json --showstat
Error output: 
Error: The --json and --showstat options cannot be used together.
Why? These options provide different output formats for different use cases:
  • --json is for machine-readable output (CI/CD integration)
  • --showstat is for human-readable statistics (local development)
Using both would create conflicting output formats.

​
When to Use Each Option

​
Use --config when:

  • Working with multiple projects or environments
  • Testing different configuration settings
  • Your configuration file is not in the default location
  • Running Linkspector from a different directory

​
Use --json when:

  • Integrating with CI/CD pipelines
  • Parsing results programmatically
  • Using with code review tools like Reviewdog
  • Generating reports in other formats
  • Need precise location information for errors

​
Use --showstat when:

  • Running checks locally during development
  • Want to see overall health of your documentation
  • Need to understand the distribution of link types
  • Monitoring link quality over time
  • Generating summary reports for stakeholders

​
Examples by Use Case

​
Local Development

# Quick check with visual feedback
linkspector check

# Detailed statistics for local testing
linkspector check --showstat

​
CI/CD Integration

# GitHub Actions, GitLab CI, etc.
linkspector check --json > linkspector-results.json

# With custom config in CI
linkspector check --config .linkspector.ci.yml --json

​
Multiple Environments

# Development environment
linkspector check --config .linkspector.dev.yml

# Production environment
linkspector check --config .linkspector.prod.yml --showstat

​
Documentation Quality Reports

# Generate human-readable statistics
linkspector check --showstat > weekly-report.txt

# Generate machine-readable data
linkspector check --json > quality-metrics.json

Build docs developers (and LLMs) love

Get started for freeTalk to us