nimble-extract-reference

What this skill does

# nimble extract — reference

Fetches a URL and returns its content. The workhorse command — use for any URL where no agent exists.

## Table of Contents

- [Parameters](#parameters)
- [Drivers](#drivers)
- [CLI](#cli)
- [Python SDK](#python-sdk)
- [Render tiers — escalate on failure](#render-tiers--escalate-on-failure)
- [Browser actions](#browser-actions)
- [Network capture](#network-capture)
- [Parser schemas — structured extraction](#parser-schemas--structured-extraction)
- [Geo targeting](#geo-targeting)
- [Async extract](#async-extract)
- [Batch extract](#batch-extract)
- [Parallelization](#parallelization)
- [Response](#response)

---

## Parameters

| Parameter         | CLI flag            | Type   | Default | Description                                                                 |
| ----------------- | ------------------- | ------ | ------- | --------------------------------------------------------------------------- |
| `url`             | `--url`             | string | —       | Target URL (**required**)                                                   |
| `render`          | `--render`          | bool   | false   | Enable headless browser (JS rendering)                                      |
| `driver`          | `--driver`          | string | `vx6`   | Engine: `vx6` · `vx8` · `vx8-pro` · `vx10` · `vx10-pro` — see Drivers table |
| `formats`         | `--format`          | array  | `["html"]` | Output format(s): `"html"`, `"markdown"`. CLI: string (`--format markdown`). SDK: array (`formats=["markdown"]`). |
| `parse`           | `--parse`           | bool   | false   | Enable parser (use with `parser`)                                           |
| `parser`          | `--parser`          | JSON   | —       | Extraction schema — see [parsing-schema.md](parsing-schema.md)              |
| `browser_actions` | `--browser-action`  | JSON   | —       | Browser actions sequence — see [browser-actions.md](browser-actions.md)     |
| `network_capture` | `--network-capture` | JSON   | —       | XHR intercept rules — see [network-capture.md](network-capture.md)          |
| `is_xhr`          | `--is-xhr`          | bool   | false   | Direct API call — no browser, no render                                     |
| `country`         | `--country`         | string | —       | ISO Alpha-2 geo proxy (e.g. `US`, `GB`)                                     |
| `state`           | `--state`           | string | —       | State-level geo targeting                                                   |
| `city`            | `--city`            | string | —       | City-level geo targeting                                                    |
| `locale`          | `--locale`          | string | —       | LCID locale (e.g. `en-US`, `fr-FR`) — pair with `country`                   |
| `method`          | `--method`          | string | `GET`   | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`                        |
| `tag`             | `--tag`             | string | —       | Request tag for analytics                                                   |

---

## Drivers

| Driver     | Description       | Render | Best for                       |
| ---------- | ----------------- | ------ | ------------------------------ |
| `vx6`      | Fast HTTP (no JS) | No     | Static HTML, APIs, high volume |
| `vx8`      | Headless browser  | Yes    | Dynamic sites, SPAs            |
| `vx8-pro`  | Headful browser   | Yes    | Complex interactions           |
| `vx10`     | Stealth headless  | Yes    | Bot-protected sites            |
| `vx10-pro` | Stealth headful   | Yes    | Most protected sites           |

---

## CLI

```bash
# Markdown output (default for most tasks)
nimble --transform "data.markdown" extract \
  --url "https://example.com/page" --format markdown

# Save to file
nimble --transform "data.markdown" extract \
  --url "https://example.com/page" --format markdown > .nimble/page.md
```

## Python SDK

```python
from nimble_python import Nimble

nimble = Nimble()
resp = nimble.extract(url="https://example.com/page", formats=["markdown"])
print(resp["data"]["markdown"])
```

---

## Render tiers — escalate on failure

**Failure signals:** status 500 · empty `data.html` / `data.markdown` · "captcha" / "verify you are human" in content · login wall instead of target page

| Tier | CLI                                                                   | When                                            |
| ---- | --------------------------------------------------------------------- | ----------------------------------------------- |
| 1    | `extract --url "..."`                                                 | Static pages, docs, news, GitHub, Wikipedia, HN |
| 2    | `extract --url "..." --render`                                        | SPAs, dynamic content, JS-rendered pages        |
| 2b   | `--render --render-options '{"render_type":"idle2","timeout":60000}'` | Slow SPAs, wait for network idle                |
| 3    | `--render --driver vx10-pro`                                          | E-commerce, social, job boards — max stealth    |

```bash
# Tier 1 — no render
nimble --transform "data.markdown" extract --url "https://example.com" --format markdown

# Tier 2 — render
nimble --transform "data.markdown" extract --url "https://example.com" --render --format markdown

# Tier 3 — stealth
nimble --transform "data.markdown" extract --url "https://example.com" --render --driver vx10-pro --format markdown
```

```python
# Tier 2 — render
resp = nimble.extract(url="https://example.com", render=True, formats=["markdown"])

# Tier 3 — stealth
resp = nimble.extract(url="https://example.com", render=True, driver="vx10-pro", formats=["markdown"])
```

---

## Browser actions

For interacting with a page before extracting — clicks, scrolls, form fills, infinite scroll. Requires `render=True`.

See [browser-actions.md](browser-actions.md) for all action types and params.

```bash
nimble --transform "data.markdown" extract \
  --url "https://example.com/product" --render \
  --browser-action '[
    {"type": "click", "selector": ".tab-reviews", "required": false},
    {"type": "wait_for_element", "selector": ".review-list"}
  ]' --format markdown
```

```python
resp = nimble.extract(
    url="https://example.com/product",
    render=True,
    browser_actions=[
        {"type": "click", "selector": ".tab-reviews", "required": False},
        {"type": "wait_for_element", "selector": ".review-list"},
    ],
    formats=["markdown"],
)
```

---

## Network capture

When page data comes from XHR/AJAX calls, or to call a known API endpoint directly with `--is-xhr`.

See [network-capture.md](network-capture.md) for filter syntax and `--is-xhr` mode.

```bash
# Intercept an API call triggered by the page
nimble extract \
  --url "https://example.com/products" --render \
  --network-capture '[{"url": {"type": "contains", "value": "/api/products"}, "resource_type": ["xhr", "fetch"]}]' \
  > .nimble/products-api.json

# Known public API endpoint — use --is-xhr (no browser, fastest)
nimble --transform "data.markdown" extract \
  --url "https://api.example.com/v1/markets?q=elections&limit=50" \
  --is-xhr --format markdown
```

```python
# Intercept via render
resp = nimble.extract(
    url="https://example.com/products",
    render=True,
    network_capture=[{"url": {"type": "contains", "value": "/api/products"}, "resource_type": ["xhr", "fetch"]}],
)
captures = resp["data"]["network_capture"]

# Direct API call — no browser
resp = nimble.extract(
    url="https://api.example.com/v1/markets?q=elections&limit=50",
    is_xhr=True,
)
```

> **Note:** `is_xhr` and `render` are mutually exclusive.

---

## Parser schemas — structured extraction

When markdown doesn't contain fields cleanly. Results land in `data.parsing`.

See [parsing-schema.md](parsing-schema.md) for selector types, extractors, and post-processors.

```bash
nimble extract --url "https://example.com/produc