lychee(1) General Commands Manual lychee(1)

lychee - بررسی‌کننده سریع و ناهمگام پیوندها

lychee [-a|--accept] [--accept-timeouts] [--archive] [-b|--base-url] [--base] [--basic-auth] [-c|--config] [--cache] [--cache-exclude-status] [--cookie-jar] [--default-extension] [--dump] [--dump-inputs] [-E|--exclude-all-private] [--exclude] [--exclude-file] [--exclude-link-local] [--exclude-loopback] [--exclude-path] [--exclude-private] [--extensions] [-f|--format] [--fallback-extensions] [--files-from] [--generate] [--github-token] [--glob-ignore-case] [-h|--help] [-H|--header] [--hidden] [--host-concurrency] [--host-request-interval] [--host-stats] [-i|--insecure] [--include] [--include-fragments] [--include-mail] [--include-verbatim] [--include-wikilinks] [--index-files] [-m|--max-redirects] [--max-cache-age] [--max-concurrency] [--max-retries] [--min-tls] [--mode] [-n|--no-progress] [--no-ignore] [-o|--output] [--offline] [-p|--preprocess] [-q|--quiet]... [-r|--retry-wait-time] [--remap] [--require-https] [--root-dir] [-s|--scheme] [--skip-missing] [--suggest] [-t|--timeout] [-T|--threads] [-u|--user-agent] [-v|--verbose]... [-V|--version] [-X|--method] [inputs]

دستور lychee یک ابزار سریع و ناهمگام (asynchronous) برای بررسی پیوندها است که پیوندها و نشانی‌های ایمیل شکسته و نامعتبر را در فایل‌های محلی و وب‌سایت‌ها شناسایی می‌کند. این ابزار از فرمت‌های Markdown و HTML پشتیبانی کرده و با سایر فرمت‌های فایل نیز کار می‌کند.

ابزار lychee بر پایه کتابخانه lychee-lib توسعه یافته است که کتابخانه‌ای به زبان راست (Rust) برای بررسی پیوندها می‌باشد.

فهرستی از کدهای وضعیت (status codes) پذیرفته‌شده برای پیوندهای معتبر.

از ساختار بازه زیر پشتیبانی می‌شود: [start]..[[=]end]|code. چند نمونه معتبر عبارتند از:

- 200 (تنها کد وضعیت 200 را می‌پذیرد)
- ..204 (هر کد وضعیت کمتر از 204 را می‌پذیرد)
- ..=204 (هر کد وضعیت کمتر یا مساوی 204 را می‌پذیرد)
- 200..=204 (هر کد وضعیت از 200 تا 204 به‌صورت فراگیر را می‌پذیرد)
- 200..205 (هر کد وضعیت از 200 تا 205 به‌جز 205 را می‌پذیرد، معادل 200..=204)

برای مشخص کردن فهرستی از کدهای وضعیت پذیرفته‌شده که با کاما از هم جدا شده‌اند، از دستور lychee --accept '200..=204, 429, 500' <inputs>... استفاده کنید. این مثال کدهای 200، 201، 202، 203، 204، 429 و 500 را به عنوان کدهای وضعیت معتبر می‌پذیرد.

[پیش‌فرض: 100..=103,200..=299]

پذیرش درخواست‌های با خطای انقضای زمان (timeout) و بازگرداندن کد خروج 0 در هنگام مواجهه با این خطاها (در صورتی که هیچ خطای دیگری رخ نداده باشد).
آرشیو وبی که برای ارائه پیشنهادات توسط گزینه --suggest استفاده می‌شود.

[پیش‌فرض: wayback]

مقادیر ممکن:

•
wayback
نشانی پایه (Base URL) برای حل کردن نشانی‌های نسبی در فایل‌های محلی. در صورت تعیین، پیوندهای نسبی در فایل‌های محلی نسبت به این نشانی پایه تفسیر می‌شوند.

برای نمونه، با داشتن نشانی پایه https://example.com/dir/page، پیوند a به https://example.com/dir/a و پیوند /b به https://example.com/b تبدیل می‌شود. این رفتار تحت تأثیر مسیر فایل‌سیستمی فایلی که شامل این پیوندها است قرار نمی‌گیرد.

توجه داشته باشید که نشانی‌های نسبی بدون اسلش آغازین، هم‌سطح (هم‌ردیف) با نشانی پایه در نظر گرفته می‌شوند. اگر نشانی پایه به اسلش ختم شود، پیوند به زیرمجموعه نشانی پایه تبدیل می‌شود. به عنوان مثال، نشانی پایه https://example.com/dir/page/ و پیوند a به https://example.com/dir/page/a حل می‌شود.

به‌طور کلی، گزینه نشانی پایه، پیوندها را طوری حل می‌کند که گویی فایل‌های محلی روی آدرس نشانی پایه مشخص‌شده میزبانی شده‌اند.

مقدار ارائه‌شده برای نشانی پایه باید یک URL (همراه با طرحواره/scheme) یا یک مسیر مطلق باشد. توجه داشته باشید که برخی از طرحواره‌های URL مانند data و mailto را نمی‌توان به عنوان پایه استفاده کرد.

منسوخ شده است؛ به جای آن از --base-url استفاده کنید.
پشتیبانی از احراز هویت پایه (Basic Authentication). مانند: http://example.com username:password
فایل پیکربندی مورد استفاده. این گزینه می‌تواند چندین بار مشخص شود.

در صورت تکرار، پیکربندی‌ها با یکدیگر ادغام می‌شوند و مقادیر مشخص‌شده در موارد بعدی، اولویت بالاتری نسبت به موارد قبلی خواهند داشت.

[پیش‌فرض: lychee.toml]

استفاده از حافظه موقت (کش) درخواست‌ها که روی دیسک در مسیر .lycheecache ذخیره می‌شود.
فهرستی از کدهای وضعیت که در حافظه موقت (کش) نادیده گرفته خواهند شد.

از ساختار بازه زیر برای مستثنی کردن پشتیبانی می‌شود: [start]..[[=]end]|code. چند نمونه معتبر عبارتند از:

- 429 (تنها کد وضعیت 429 را مستثنی می‌کند)
- 500.. (هر کد وضعیت بزرگتر یا مساوی 500 را مستثنی می‌کند)
- ..100 (هر کد وضعیت کمتر از 100 را مستثنی می‌کند)
- 500..=599 (هر کد وضعیت از 500 تا 599 به‌صورت فراگیر را مستثنی می‌کند)
- 500..600 (هر کد وضعیت از 500 تا 600 به‌جز 600 را مستثنی می‌کند، معادل 500..=599)

برای مشخص کردن فهرستی از کدهای وضعیت مستثنی‌شده که با کاما از هم جدا شده‌اند، از دستور lychee --cache-exclude-status '429, 500..502' <inputs>... استفاده کنید. این مثال نتایج با کدهای وضعیت 429، 500 و 501 را در حافظه موقت ذخیره نمی‌کند.

خواندن و نوشتن کوکی‌ها با استفاده از فایل مشخص‌شده. کوکی‌ها در این فایل ذخیره شده و همراه با درخواست‌ها ارسال می‌شوند. کوکی‌های جدید در فایل ذخیره شده و کوکی‌های موجود به‌روزرسانی خواهند شد.
پسوند پیش‌فرضی که برای فایل‌های فاقد پسوند اعمال می‌شود.

این گزینه برای فایل‌های بدون پسوند یا با پسوند ناشناخته مفید است. از این پسوند برای تشخیص نوع فایل و پردازش آن استفاده می‌شود.

مثال‌ها:

--default-extension md
--default-extension html
هیچ بررسی پیوندی انجام نده؛ در عوض، تمام پیوندهای استخراج‌شده از ورودی‌ها را که قرار بود بررسی شوند چاپ کن.
هیچ استخراج و بررسی پیوندی انجام نده؛ در عوض، تمام منابع ورودی را که قرار بود پیوندها از آن‌ها جمع‌آوری شوند چاپ کن.
مستثنی کردن تمامی نشانی‌های IP خصوصی از بررسی. معادل با گزینه‌های --exclude-private --exclude-link-local --exclude-loopback.
مستثنی کردن نشانی‌های URL و آدرس‌های ایمیل از بررسی. مقادیر داده‌شده به عنوان عبارات باقاعده (regex) در نظر گرفته می‌شوند.
منسوخ شده است؛ به جای آن از --exclude-path استفاده کنید.
مستثنی کردن بازه نشانی‌های IP محلی پیوند (link-local) از بررسی.
مستثنی کردن بازه نشانی‌های IP لوپ‌بک (loopback) و localhost از بررسی.
مستثنی کردن مسیرها از بررسی شدن. مقادیر داده‌شده به عنوان عبارات باقاعده (regex) در نظر گرفته می‌شوند.
مستثنی کردن بازه‌های نشانی‌های IP خصوصی از بررسی.
فهرستی از پسوندهای فایل. فایل‌هایی که با پسوندهای مشخص‌شده مطابقت نداشته باشند نادیده گرفته می‌شوند.

می‌توان چندین پسوند را با کاما از هم جدا کرد. توجه داشته باشید اگر می‌خواهید نوع فایل‌هایی را بررسی کنید که چند پسوند مختلف دارند، برای مثال فایل‌های HTML که هر دو پسوند .html و .htm را دارند، باید هر دو پسوند را صراحتاً مشخص کنید. برای نمونه: --extensions html,htm,php,asp,aspx,jsp,cgi.

این گزینه زمانی مفید است که پسوندهای پیش‌فرض کافی نیستند و نمی‌خواهید فهرست بلندی از ورودی‌ها (مانند file1.html، file2.md و...) را مشخص کنید.

[پیش‌فرض: md,mkd,mdx,mdown,mdwn,mkdn,mkdown,markdown,html,htm,css,txt,xml]

فرمت خروجی گزارش وضعیت نهایی.

[پیش‌فرض: compact]

مقادیر ممکن:

  • compact
  • detailed
  • json
  • junit
  • markdown
هنگام بررسی محلی، با آزمودن پسوندهای جایگزین (fallback) ارائه‌شده تلاش می‌کند فایل‌های ناموجود را پیدا کند. چندین پسوند را می‌توان با کاما از هم جدا کرد. پسوندها به ترتیب ذکر شدن بررسی خواهند شد.

مثال: --fallback-extensions html,htm,php,asp,aspx,jsp,cgi

نکته: این گزینه روی شناسه‌های file:// که وجود ندارند و همچنین شناسه‌های file:// که به پوشه‌هایی اشاره می‌کنند که به خودشان ارجاع داده می‌شوند (طبق منطق --index-files) اثر می‌گذارد.

خواندن نام فایل‌های ورودی از فایل داده‌شده یا از ورودی استاندارد (اگر مسیر برابر '-' باشد).

این گزینه زمانی مفید است که تعداد زیادی ورودی دارید و مشخص کردن مستقیم همه آن‌ها در خط فرمان دشوار است.

مثال‌ها:

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

فرمت فایل:

- هر خط باید شامل یک ورودی باشد (مسیر فایل، URL، یا الگوی glob).
- خطوطی که با '#' شروع شوند به عنوان کامنت در نظر گرفته شده و نادیده گرفته می‌شوند.
- خطوط خالی نیز نادیده گرفته می‌شوند.
تولید خروجی‌های ویژه (مانند صفحه راهنما/man) به جای انجام بررسی پیوندها.

مقادیر ممکن:

  • man
  • complete-bash
  • complete-elvish
  • complete-fish
  • complete-powershell
  • complete-zsh
توکن API گیت‌هاب جهت استفاده هنگام بررسی پیوندهای github.com، برای جلوگیری از محدودیت نرخ درخواست (rate limiting).
نادیده گرفتن بزرگی و کوچکی حروف هنگام باز کردن الگوهای glob مسیر فایل‌سیستم در ورودی‌ها.
نمایش راهنما (مشاهده خلاصه با -h).
تنظیم هدر سفارشی برای درخواست‌ها.

برخی از وب‌سایت‌ها برای بازگرداندن پاسخ‌های معتبر نیازمند هدرهای سفارشی هستند. می‌توانید هدرهای سفارشی را با فرمت 'Name: Value' مشخص کنید؛ به عنوان مثال 'Accept: text/html'. این همان فرمتی است که ابزارهای دیگری مانند curl یا wget استفاده می‌کنند. می‌توان با تکرار این فلگ، چندین هدر را مشخص کرد. هدرهای تعیین‌شده برای تمامی درخواست‌ها اعمال می‌شوند. برای پیکربندی هدرها به تفکیک هر میزبان، از گزینه hosts استفاده کنید.

فایل‌ها و دایرکتوری‌های مخفی را نادیده نگیر.
حداکثر تعداد پیش‌فرض درخواست‌های همزمان به ازای هر میزبان (پیش‌فرض: 10).

این گزینه حداکثر تعداد درخواست‌هایی را که به‌طور همزمان به یک میزبان ارسال می‌شوند محدود می‌کند؛ این کار مانع از بارگذاری بیش از حد روی سرورها و برخورد با محدودیت‌های نرخ درخواست (rate limits) می‌شود. برای پیکربندی این مورد به ازای هر میزبان، از گزینه hosts استفاده کنید.

مثال‌ها:

--host-concurrency 2   # محتاطانه برای APIهای کند
--host-concurrency 20  # تهاجمی برای APIهای سریع
حداقل فاصله زمانی بین درخواست‌ها به یک میزبان یکسان (پیش‌فرض: 50ms).

یک تأخیر پایه بین درخواست‌های متوالی تنظیم می‌کند تا از بارگذاری بیش از حد سرورها جلوگیری شود. الگوریتم تطبیقی ممکن است بر اساس پاسخ‌های سرور (محدودیت‌های نرخ درخواست یا خطاها) این مقدار را افزایش دهد. برای تنظیم این مورد به ازای هر میزبان، از گزینه hosts استفاده کنید.

مثال‌ها:

--host-request-interval 50ms   # سریع برای APIهای پایدار
--host-request-interval 1s     # محتاطانه برای APIهای دارای محدودیت نرخ
نمایش آمار به تفکیک میزبان‌ها در پایان اجرا.
ادامه دادن اتصال به سرورهایی که ناامن تلقی می‌شوند (گواهی TLS نامعتبر).
نشانی‌های URL برای بررسی (پشتیبانی از عبارات باقاعده). این گزینه بر تمام استثناها اولویت دارد.
فعال‌سازی بررسی قطعات (fragments) در پیوندها.

از none برای غیرفعال کردن بررسی قطعات، از anchor-only برای قطعات لنگر (anchor) مانند #section، از text-only برای قطعات متنی مانند #:~:text=example، یا از full برای بررسی هر دو حالت استفاده کنید.

در صورت ارائه بدون مقدار، پیش‌فرض روی anchor-only خواهد بود.

بررسی نشانی‌های ایمیل علاوه بر پیوندها.
یافتن پیوندها در بخش‌های عینی و متنی مانند بلوک‌های pre و code.
بررسی ویکی‌لینک‌ها (WikiLinks) در فایل‌های Markdown؛ این گزینه نیازمند تعیین --base-url است.
هنگام بررسی محلی، پیوندهای دایرکتوری را به یک فایل شاخص (index) مجزا نگاشت می‌دهد. آرگومان ورودی فهرستی از نام‌های فایل‌های شاخص است که با کاما از هم جدا شده‌اند. نام‌های شاخص نسبت به دایرکتوری پیوند سنجیده شده و به ترتیب مشخص‌شده بررسی می‌شوند.

اگر گزینه --index-files مشخص شود، برای معتبر شناخته شدن پیوند دایرکتوری، دست‌کم یکی از فایل‌های شاخص باید وجود داشته باشد. علاوه بر این، می‌توان از نام ویژه . در فهرست استفاده کرد تا به خود دایرکتوری اشاره شود.

در صورت عدم تعیین (رفتار پیش‌فرض)، فایل‌های شاخص غیرفعال هستند و پیوندهای دایرکتوری تا زمانی که دایرکتوری روی دیسک وجود داشته باشد معتبر تلقی می‌شوند.

مثال ۱: `--index-files index.html,readme.md` به دنبال index.html یا readme.md
        می‌گردد و وجود دست‌کم یکی از آن‌ها الزامی است.
مثال ۲: `--index-files index.html,.` در صورت وجود از index.html استفاده می‌کند،
        اما در هر حال پیوند دایرکتوری را نیز می‌پذیرد.
مثال ۳: `--index-files ''` تمام پیوندهای دایرکتوری را رد می‌کند، زیرا هیچ
        فایل شاخص معتبری وجود ندارد. این امر مستلزم آن است که هر پیوند صراحتاً
        نام یک فایل را ذکر کند.

نکته: این گزینه تنها روی شناسه‌های file:// که وجود دارند و به یک دایرکتوری اشاره می‌کنند اعمال می‌شود.

حداکثر تعداد مجاز تغییر مسیرها (redirects).

[پیش‌فرض: 10]

دور انداختن تمام درخواست‌های ذخیره‌شده در حافظه موقت (کش) که قدیمی‌تر از این مدت زمان هستند.

[پیش‌فرض: 1d]

حداکثر تعداد درخواست‌های شبکه به صورت همزمان.

[پیش‌فرض: 128]

حداکثر تعداد تلاش‌های مجدد به ازای هر درخواست.

[پیش‌فرض: 3]

حداقل نسخه پذیرفته‌شده TLS.

مقادیر ممکن:

  • TLSv1_0
  • TLSv1_1
  • TLSv1_2
  • TLSv1_3
تنظیم حالت نمایش خروجی. نحوه نمایش نتایج در ترمینال را تعیین می‌کند.

[پیش‌فرض: color]

مقادیر ممکن:

  • plain
  • color
  • emoji
  • task
نوار پیشرفت را نمایش نده. این گزینه برای پوسته‌های غیرتعاملی (مانند محیط‌های یکپارچه‌سازی مداوم / CI) پیشنهاد می‌شود.
فایل‌هایی را که معمولاً توسط '.gitignore'، '.ignore' یا فایل نادیده‌گیری سراسری (global ignore) نادیده گرفته می‌شوند، رد نکن.
فایل خروجی گزارش وضعیت.
تنها فایل‌های محلی را بررسی کرده و درخواست‌های شبکه را مسدود کن.
پیش‌پردازش فایل‌های ورودی با دستور مشخص‌شده.

به ازای هر فایل ورودی، این فلگ باعث می‌شود lychee دستور COMMAND PATH را اجرا کرده و به جای محتوای اصلی مسیر، خروجی استاندارد آن را پردازش کند. این ویژگی به شما امکان می‌دهد فایل‌هایی را که در حالت عادی توسط lychee قابل فهم نیستند تبدیل کنید. دستور پیش‌پردازشگر تنها روی فایل‌های ورودی اجرا می‌شود، نه روی ورودی استاندارد یا نشانی‌های URL.

برای فراخوانی برنامه‌ها با آرگومان‌های سفارشی یا استفاده از چند پیش‌پردازشگر، از یک برنامه پوششی (wrapper) مانند اسکریپت شل استفاده کنید. نمونه‌ای از این اسکریپت به شکل زیر است:

#!/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
    ;;
*)
    # تابع همانی، چاپ ورودی بدون تغییر
    exec cat
    ;;
esac
کاهش خروجی در هر بار تکرار (مانند -q یا -qq).
حداقل زمان انتظار (بر حسب ثانیه) بین تلاش‌های مجدد برای درخواست‌های ناموفق.

[پیش‌فرض: 1]

بازنگاشت شناسه‌های URI منطبق با الگو به یک URI متفاوت.
در صورت در دسترس بودن پروتکل HTTPS، پیوندهای HTTP را به عنوان خطا در نظر بگیر.
دایرکتوری ریشه جهت استفاده هنگام بررسی پیوندهای مطلق در فایل‌های محلی. اگر پیوندهای مطلق در فایل‌های محلی وجود داشته باشند این گزینه الزامی است؛ در غیر این صورت آن پیوندها به عنوان خطا علامت‌گذاری می‌شوند. این مسیر باید یک مسیر مطلق باشد (یعنی با / شروع شود).

در صورت مشخص شدن، پیوندهای مطلق در فایل‌های محلی با افزودن دایرکتوری ریشه داده‌شده به ابتدای پیوند مطلق درخواستی حل می‌شوند. برای مثال، با دایرکتوری ریشه /root/dir، پیوند به /page.html به صورت /root/dir/page.html حل خواهد شد.

این گزینه می‌تواند همراه با گزینه --base-url نیز مشخص شود. اگر هر دو ارائه شوند، پیوند مطلق با ایجاد یک URL مرکب از سه بخش حل می‌شود: نام دامنه مشخص‌شده در --base-url، سپس مسیر دایرکتوری --root-dir و در نهایت مسیر خود پیوند مطلق.

تنها پیوندهایی را که دارای طرحواره‌های (schemes) مشخص‌شده هستند (مانند https) آزمایش کن. در صورت عدم درج، پیوندها با هر طرحواره دیگری بررسی می‌شوند. در حال حاضر، از طرحواره‌های http، https، file و mailto پشتیبانی می‌شود.
رد کردن فایل‌های ورودی ناموجود (رفتار پیش‌فرض، اعلام خطا در صورت عدم وجود آن‌ها است).
پیشنهاد پیوندهای جایگزین برای پیوندهای شکسته با استفاده از آرشیو وب. آرشیو وب را می‌توان با گزینه --archive تعیین کرد.
مدت زمان انقضای وب‌سایت بر حسب ثانیه، از زمان اتصال تا پایان دریافت پاسخ.

[پیش‌فرض: 20]

تعداد ریسمان‌های پردازشی (threads) مورد استفاده. پیش‌فرض برابر با تعداد هسته‌های پردازشی موجود در سیستم است.
عامل کاربر (User Agent).

[پیش‌فرض: lychee/x.y.z]

تنظیم سطح پرگویی (verbosity)؛ تولید خروجی بیشتر با هر بار تکرار گزینه (مانند -v یا -vv).
نمایش نسخه برنامه.
روش ارسال درخواست (HTTP Request Method).

[پیش‌فرض: get]

[inputs]
ورودی‌های بررسی پیوند (منابعی که پیوندها برای بررسی از آن‌ها دریافت می‌شوند). این ورودی‌ها می‌توانند شامل موارد زیر باشند: فایل‌ها (مانند README.md)، الگوهای سراسری فایل (مانند '~/git/*/README.md')، نشانی‌های دوردست (مانند https://example.com/README.md)، یا ورودی استاندارد (-). همچنین می‌توانید از گزینه --files-from برای خواندن ورودی‌ها از یک فایل استفاده کنید.

نکته: از -- برای جدا کردن ورودی‌ها از گزینه‌هایی که چندین آرگومان می‌پذیرند استفاده کنید.

بررسی تمام پیوندها در فایل‌های پشتیبانی‌شده با مشخص کردن یک دایرکتوری:

$ lychee .

مشخص کردن صریح فایل‌ها یا استفاده از الگوهای glob:

$ lychee README.md test.html info.txt
$ lychee 'public/**/*.html' '*.md'

بررسی تمامی پیوندهای یک وب‌سایت:

$ lychee https://example.com

بررسی پیوندها از طریق ورودی استاندارد (stdin):

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

مستثنی کردن یا گنجاندن پیوندها با استفاده از عبارات باقاعده:

$ lychee --exclude '^https?://blog\.example\.com' --exclude '\.(pdf|zip|png|jpg)$' .

مثال‌های بیشتر را می‌توانید در مستندات برخط به نشانی https://lychee.cli.rs مشاهده فرمایید.

0
موفقیت. عملیات طبق دستور با موفقیت به پایان رسید.
1
ورودی‌های ناموجود، خطاهای غیرمنتظره در زمان اجرا یا خطاهای پیکربندی.
2
شکست در بررسی پیوندها. دست‌کم یک پیوند مستثنی‌نشده در بررسی با شکست مواجه شد.
3
بروز خطا در فایل پیکربندی.

گزارش هرگونه اشکال یا پرسش به نشانی https://github.com/lycheeverse/lychee/issues.

همچنین می‌توانید سوالات خود را در نشانی زیر مطرح کنید: https://github.com/lycheeverse/lychee/discussions.

v0.24.2

Matthias Endler <matthias@endler.dev>
Thomas Zahner <thomas.zahner@protonmail.ch>

با سپاس و قدردانی فراوان از تمامی مشارکت‌کنندگان فوق‌العاده‌ای که به موفقیت این پروژه کمک کردند.

2026-05-01 lychee 0.24.2