Epeira

Definition

epeira (noun): a spider of the genus Araneus

Description

Epeira is a Node.js CLI and library to help transform the web into usable output: markdown, JSON, and PDF.

It is built around one command surface:

• epeira <url...> [options]
• epeira --url <url> [--url <url> ...] [options]

Out of the box, epeira can:

• fetch one or more URLs
• normalize fetched content into a shared runtime shape
• render readable markdown output
• emit stable JSON output for automation
• return pass-through fetched-content objects for inspection
• render JavaScript-heavy pages through a browser-backed fetch path
• route PDF content through the markdown-oriented output path
• persist and reuse browser cookie/session state for continuity across runs

This package is currently built and verified on Node.js 24.x.

Installation

Install globally when you want the native epeira command available in your shell:

npm install -g @tadalabz/epeira
epeira https://example.com

Install locally when you want to run it through npx or npm exec:

npm install @tadalabz/epeira
npx epeira https://example.com

CLI Summary

For full command syntax, examples, and behavior details, use docs/USAGE.md.

epeira https://example.com
epeira https://example.com --output json
epeira https://example.com --output json --json-metadata-only
epeira https://example.com --output pdf --out content.pdf
epeira https://example.com --output no-op
epeira --url https://example.com --url https://example.org --continue-on-error

Options

• --output markdown|json|pdf|no-op (default: markdown)
• --json-metadata-only (JSON only)
• --url <value> (repeatable)
• --timeout <ms>
• --render-js
• --render-wait-ms <ms>
• --user-agent <value>
• --skip-tls-verify (insecure)
• --session-state-in <path>
• --session-state-out <path>
• --session-profile <name>
• --challenge-policy report|fail|fail-with-guidance
• --continue-on-error
• --out <path>
• --help

Exit Codes

• 0: all URLs succeeded
• 1: failure, or stopped on first failure
• 2: partial success with --continue-on-error
• 3: challenge encountered with --challenge-policy fail|fail-with-guidance

Best Fit

Epeira is a strong fit when you want:

• one focused tool that turns web pages into dependable, reusable content output
• consistent results across multiple URLs in a single run
• content that can serve both people (readable output) and systems (structured output)
• a simple way to work with mixed web inputs, including rendered pages and PDFs, through one workflow

Quality Statement

Epeira is validated with automated tests across the CLI contract, fetch normalization, formatter behavior, and packaged deliverable surface. These checks confirm output-mode behavior, multi-URL handling, error semantics, and PDF routing.

Canonical Scope

This document is the high-level introduction to the package.

It tells you:

• what epeira is
• what runtime behavior it owns
• what the published package contains
• where to go next for command and output details

Published Surface

The published package includes:

• README.md: this high-level package summary
• bin/epeira: public CLI entrypoint
• src/: runtime implementation
• LICENSE: license text

CHANGELOG

v1.1.0

• Added cookie/session-state controls: --session-state-in, --session-state-out, and --session-profile.
• Added challenge response policy control: --challenge-policy report|fail|fail-with-guidance.
• Added dedicated challenge exit code 3 for fail-on-challenge policy modes.
• Added deterministic operator guidance output in fail-with-guidance mode.

v1.0.0

• Initial release of epeira CLI with URL fetch pipeline and formatter outputs: markdown (default), json, pdf, and no-op.
• Support for single and multi-URL workflows via positional URLs and repeatable --url.
• Operator controls for timeout, JS rendering, custom user-agent, TLS-verify bypass, continue-on-error, and file output.