CLI Reference

seaportal [options] <url>          # Extract Markdown / JSON / snapshot (default verb)
seaportal sitemap <url> [flags]    # Flatten a sitemap.xml (recurses sitemap-index)
seaportal feed <url> [flags]       # Parse RSS / Atom / JSON Feed into unified entries
seaportal scrape <base-url> [flags] # Scrape a whole site (discover, sample, extract) → structured JSON
seaportal mcp                      # Run as an MCP server over stdio (see mcp.md)
seaportal help                     # Show usage
seaportal version                  # Show version (also --version / -v)

The default verb extracts a URL and prints the content plus a classification summary to stdout. Pass --save-dir <dir> to also write the rendered Markdown and JSON to <dir>/<host>_<timestamp>.{md,json}. Use --json, --xml, or the snapshot subcommand to control the format.

Input modes

• URL: seaportal https://example.com
• stdin HTML: pipe HTML and pass --base-url to resolve relative links:
  terminal

  cat page.html | seaportal --base-url https://example.com

  CP
  In stdin mode, --head-only, --respect-robots, and --retries are ignored.

Content types

seaportal routes a response by its Content-Type:

• HTML (text/html, application/xhtml+xml) → readability + HTML→markdown.
• PDF (application/pdf) → text extraction (disable with --no-pdf).
• JSON / XML (application/json, application/xml, text/xml, and +json/+xml variants) → returned verbatim, without markdown escaping, so structured bodies stay valid (a JSON "node_id" is not corrupted into "node\_id").
• Other text (text/plain, text/csv) → returned as-is.
• Binary (images, archives, application/octet-stream, …) → skipped with a “skipped binary content” error.

Extract flags

Cache

Query / BM25

Split output

Security

The CLI is safe by default: it applies DefaultSecurityPolicy() (SSRF / private-IP block on, http/https only, redirect + body caps). Loosen it only for trusted targets — e.g. --allow-internal to reach localhost / a private host. See SECURITY.md for the threat model and coverage caveats (--proxy skips the dial-time rebinding check).

Snapshot flags

seaportal sitemap

seaportal sitemap https://example.com/sitemap.xml [--json] [--max-urls N] [--max-depth N]

Recurses nested <sitemapindex> references and auto-decompresses .gz sitemaps.

seaportal feed

seaportal feed https://example.com/feed.xml [--json] [--max-items N]

Parses RSS 2.0, Atom 1.0, and JSON Feed 1.x into unified entries.

seaportal scrape

Scrape a whole website from a base URL: discover candidate URLs (robots.txt + sitemap, or a bounded crawl fallback), cluster them into pattern groups, sample within budget, fetch and extract each page concurrently, and emit a structured result. The JSON output is designed to be handed to PinchTab for deep browser enrichment (screenshots, console/network capture, visual regression, a11y checks).

seaportal scrape https://example.com --max-pages 50 --sample-strategy balanced

Every scrape fetch (discovery, robots.txt, sitemaps, pages) runs under the secure-by-default policy (private-IP block, http/https only, redirect and size caps); --allow-internal lifts only the private-IP block. If the run is interrupted (Ctrl-C) the partial result is still rendered, with a warning on stderr and a non-zero exit code.

Sampling strategies: balanced spreads the budget across groups so a large group can’t starve the others; priority takes the homepage and one representative per top-level section first; random samples uniformly within each group (seeded per-site for reproducibility). --full turns off the per-pattern cap but --max-pages remains the overall budget, so to fetch every page of a large site raise --max-pages accordingly (e.g. --full --max-pages 1000). --output directory writes result.json, one pages/<slug>.md per page, and an index.md manifest.

Sample JSON output (abridged):

{
  "site": {
    "baseURL": "https://example.com",
    "title": "Example Site",
    "sitemapFound": true,
    "totalURLsInSitemap": 12450,
    "sampledPages": 42
  },
  "pageGroups": [
    { "pattern": "/blog/*", "totalInSitemap": 8200, "sampled": 8, "pages": [] }
  ],
  "pages": [
    {
      "url": "https://example.com/blog/hello",
      "title": "Hello",
      "status": 200,
      "meta": { "title": "Hello", "ogType": "article" },
      "markdown": "# Hello\n\n…",
      "schema": [ { "type": "Article" } ],
      "contentType": "article",
      "internalLinks": 45,
      "externalLinks": 12
    }
  ],
  "summary": {
    "contentTypes": { "article": 30, "product": 10, "page": 2 },
    "recommendations": ["sitemap lists 12450 URLs across 6 patterns but only 42 were sampled; sampling recommended"]
  }
}