CLI

The Reader CLI lets you scrape, crawl, and take screenshots from the command line. It’s a thin wrapper around the Reader API - no local browser needed. Built for AI coding agents like Claude Code, Cursor, and Codex, but works great for humans too.

Install

npm install -g @vakra-dev/reader-cli

Or run directly without installing:

npx @vakra-dev/reader-cli scrape https://example.com

Authentication

For humans
For AI agents / CI

Run once to save your API key:

reader config set api-key rdr_your_key_here

The key is saved to ~/.reader/config.json and used for all future commands.

Set the environment variable:

export READER_API_KEY=rdr_your_key_here

The env var takes precedence over the config file. No disk writes needed.

Get your API key from the Reader dashboard.

Scrape a page

reader scrape https://example.com

Output is clean markdown, printed to stdout. Pipe it anywhere:

reader scrape https://docs.stripe.com/payments > stripe-payments.md

Formats

reader scrape https://example.com                    # markdown (default)
reader scrape https://example.com -f html             # cleaned HTML
reader scrape https://example.com -f screenshot -o page.png  # full-page PNG

JSON output

Get the full API response with metadata:

reader scrape https://example.com --json

{
  "url": "https://example.com",
  "markdown": "# Example Domain\n\n...",
  "metadata": {
    "duration": 892,
    "cached": false,
    "proxyMode": "standard"
  },
  "pageMetadata": {
    "title": "Example Domain"
  }
}

Options

reader scrape <url> [options]

Options:
  -f, --format <format>    markdown (default), html, screenshot
  --json                   Full JSON response
  -o, --output <file>      Write to file
  --no-main-content        Include nav, header, footer
  --include-tags <sel>     CSS selectors to keep (comma-separated)
  --exclude-tags <sel>     CSS selectors to remove (comma-separated)
  --wait-for <selector>    Wait for element before capturing
  --timeout <ms>           Timeout in milliseconds (default: 30000)
  --proxy-mode <mode>      standard, premium

Crawl a site

Discover and scrape all pages on a website:

reader crawl https://docs.example.com

Each page’s markdown is output separated by ---. Save to individual files:

reader crawl https://docs.example.com -o ./docs/

URL discovery only

List all discovered URLs without scraping content:

reader crawl https://docs.example.com --urls-only

Options

reader crawl <url> [options]

Options:
  --max-depth <n>          Crawl depth (default: 2)
  --max-pages <n>          Max pages (default: 20)
  --urls-only              Only list URLs, don't scrape
  --json                   Full JSON response
  -o, --output-dir <dir>   Write each page to a separate file

Check status

Verify your setup and see your credit balance:

reader status

Reader CLI v0.1.0
API:     https://api.reader.dev
Key:     rdr_...c3bb
Credits: 874 / 1000 (free tier)
Resets:  2026-07-01

Check credits

reader credits

Balance: 874 / 1000
Used:    126
Tier:    free
Resets:  2026-07-01T00:00:00.000Z

Configuration

reader config set api-key <key>     # save API key
reader config set api-url <url>     # custom API URL
reader config show                  # show current config

Config is stored at ~/.reader/config.json. Environment variables always take precedence:

Setting	Env var	Config key
API key	`READER_API_KEY`	`apiKey`
API URL	`READER_API_URL`	`apiUrl`

For AI agents

The CLI is designed to work seamlessly with AI coding agents:

Markdown to stdout - agents read the content directly
Errors to stderr - never pollutes piped output
Exit codes - 0 on success, 1 on error
No interactive prompts - everything via flags and env vars
--json flag - structured output for programmatic use

Example in a Claude Code or Cursor workflow:

# Agent reads documentation to answer a question
reader scrape https://docs.stripe.com/payments/quickstart

# Agent crawls a site for context
reader crawl https://docs.example.com --max-pages 10 -o ./context/

# Agent takes a screenshot for visual analysis
reader scrape https://example.com -f screenshot -o page.png

Get Started

Concepts

Getting Started Guides

Async Workflows

Production Patterns

Advanced Scraping

LLM & AI Use Cases

Troubleshooting

Install

Authentication

Scrape a page

Formats

JSON output

Options

Crawl a site

URL discovery only

Options

Check status

Check credits

Configuration

For AI agents

​Install

​Authentication

​Scrape a page

​Formats

​JSON output

​Options

​Crawl a site

​URL discovery only

​Options

​Check status

​Check credits

​Configuration

​For AI agents

Install

Authentication

Scrape a page

Formats

JSON output

Options

Crawl a site

URL discovery only

Options

Check status

Check credits

Configuration

For AI agents