Skip to content

cli-reference.mdx

Latest commit

 

History

History
156 lines (103 loc) · 4.47 KB

cli-reference.mdx

File metadata and controls

156 lines (103 loc) · 4.47 KB
title CLI Reference
description Complete reference for the html2rss command-line interface

This page documents the html2rss command-line interface (CLI).

For detailed documentation on the Ruby API, please refer to the official YARD documentation.

📚 View the Ruby API Docs on rubydoc.info

Commands

The html2rss executable is the primary way to interact with the gem from your terminal.

Auto

Automatically discovers items from a page and prints the generated RSS feed to stdout.

# Use the default faraday strategy
html2rss auto https://example.com/articles

# Force browserless for JavaScript-heavy pages
html2rss auto https://example.com/app --strategy browserless

# Set custom request budgets
html2rss auto https://example.com/app --strategy browserless --max-redirects 5 --max-requests 6

# Hint the item selector while keeping auto enhancement
html2rss auto https://example.com/articles --items_selector ".post-card"

Command: html2rss auto URL

URL Surface Guidance For auto

auto works best when the input URL already exposes a server-rendered list of entries.

  • High-success surfaces:
    • newsroom or press listing pages
    • blog/category/tag listing pages
    • changelog/release notes/update listing pages
    • paginated archive/list views
  • Low-success surfaces:
    • generic homepages with heavy promo/navigation chrome
    • search results pages
    • client-rendered app shells (#app, #root, #__next, etc.)

When possible, pass a direct listing/update URL instead of a top-level homepage or app entrypoint.

Failure Outcomes You Should Expect

When no extractable items are found, auto now classifies likely causes instead of only returning a generic message:

  • blocked surface likely (anti-bot or interstitial):
    • retry with --strategy browserless
    • try a more specific public listing URL
  • app-shell surface detected:
    • retry with --strategy browserless
    • switch to a direct listing/update URL
  • unsupported extraction surface for auto mode:
    • switch to listing/changelog/category URLs
    • use explicit selectors in a feed config

Known anti-bot interstitial responses (for example Cloudflare challenge pages) are surfaced explicitly as blocked-surface errors.

Browserless Setup And Diagnostics (CLI)

browserless is opt-in for CLI usage.

# Start a local Browserless container (default local token)
docker run --rm -p 3000:3000 -e "CONCURRENT=10" -e "TOKEN=6R0W53R135510" ghcr.io/browserless/chromium

# Run auto with Browserless
BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
  html2rss auto https://example.com/updates --strategy browserless

If you see Browserless connection failed, check:

  • BROWSERLESS_IO_WEBSOCKET_URL points to a reachable Browserless endpoint
  • BROWSERLESS_IO_API_TOKEN matches the Browserless TOKEN
  • the Browserless service is running and reachable from your shell environment

For custom Browserless endpoints, BROWSERLESS_IO_API_TOKEN is required.

Feed

Loads a YAML config, builds the feed, and prints the RSS XML to stdout.

# Single-feed config
html2rss feed single.yml

# Multi-feed config under the `feeds:` key
html2rss feed feeds.yml my-first-feed

# Override the request strategy at runtime
html2rss feed single.yml --strategy browserless

# Override request budgets at runtime
html2rss feed single.yml --max-redirects 5 --max-requests 6

# Pass dynamic parameters into %<param>s placeholders
html2rss feed single.yml --params id:42 foo:bar

Command: html2rss feed YAML_FILE [feed_name]

The CLI keeps strategy as a top-level override and writes runtime request limits into the generated config under request.

Schema

Prints the exported JSON Schema for the current gem version.

# Pretty-printed JSON (default)
html2rss schema

# Compact JSON
html2rss schema --no-pretty

# Write the schema to a file
html2rss schema --write tmp/html2rss-config.schema.json

Command: html2rss schema

Validate

Validates a config with the runtime validator without generating a feed.

# Validate a single-feed file
html2rss validate single.yml

# Validate one feed from a multi-feed file
html2rss validate feeds.yml my-first-feed

Command: html2rss validate YAML_FILE [feed_name]

Help

Displays the help message with available commands and options.

Command: html2rss help

Version

Displays the installed version of html2rss.

Command: html2rss --version