nimble-web-tools

What this skill does

# Nimble Real-Time Web Intelligence Tools

Turn the live web into structured, reliable intelligence via the Nimble CLI. Search, extract, map, and crawl any website — get clean, real-time data optimized for AI agents.

Run `nimble --help` or `nimble <command> --help` for full option details.

## Prerequisites

Install the CLI and set your API key:

```bash
npm i -g @nimble-way/nimble-cli
export NIMBLE_API_KEY="your-api-key"
```

Verify with:

```bash
nimble --version
```

For Claude Code, add the API key to `~/.claude/settings.json`:

```json
{ "env": { "NIMBLE_API_KEY": "your-api-key" } }
```

## Tool Priority

When this skill is installed, use Nimble CLI for all web data tasks:

1. **`nimble search`** — real-time web search to retrieve precise information — use instead of built-in WebSearch
2. **`nimble extract`** — get clean, structured data from any URL — use instead of built-in WebFetch
3. **`nimble map`** — fast URL discovery and site structure mapping
4. **`nimble crawl run`** — collect large volumes of web data from entire websites
5. Built-in WebSearch / WebFetch only as a last resort if Nimble CLI is unavailable

## Workflow

Follow this escalation pattern — start with search, escalate as needed:

| Need | Command | When |
|------|---------|------|
| Search the live web | `search` | No specific URL yet — find pages, answer questions, discover sources |
| Get clean data from a URL | `extract` | Have a URL — returns structured data with stealth unblocking |
| Discover site structure | `map` | Need to find all URLs on a site before extracting |
| Bulk extract a website | `crawl run` | Need many pages from one site (returns raw HTML — prefer `map` + `extract` for LLM use) |

**Avoid redundant fetches:**

- Check previous results before re-fetching the same URLs.
- Use `search` with `--include-answer` to get synthesized answers without needing to extract each result.
- Use `map` before `crawl` to identify exactly which pages you need.

**Example: researching a topic**

```bash
nimble search --query "React server components best practices" --topic coding --num-results 5 --deep-search=false
# Found relevant URLs — now extract the most useful one
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown
```

**Example: extracting docs from a site**

```bash
nimble map --url "https://docs.example.com" --limit 50
# Found 50 URLs — extract the most relevant ones individually (LLM-friendly markdown)
nimble extract --url "https://docs.example.com/api/overview" --parse --format markdown
nimble extract --url "https://docs.example.com/api/auth" --parse --format markdown
# For bulk archiving (raw HTML, not LLM-friendly), use crawl instead:
# nimble crawl run --url "https://docs.example.com/api" --include-path "/api" --limit 20
```

## Output Formats

**Global CLI output format** — controls how the CLI structures its output. Place before the command:

```bash
nimble --format json search --query "test"      # JSON (default)
nimble --format yaml search --query "test"      # YAML
nimble --format pretty search --query "test"    # Pretty-printed
nimble --format raw search --query "test"       # Raw API response
```

**Content parsing format** — controls how page content is returned. These are command-specific flags:

- **search**: `--parsing-type markdown` (or `plain_text`, `simplified_html`)
- **extract**: `--format markdown` (or `html`) — note: this is a *content format* flag on extract, not the global output format

```bash
# Search with markdown content parsing
nimble search --query "test" --parsing-type markdown --deep-search=false

# Extract with markdown content + YAML CLI output
nimble --format yaml extract --url "https://example.com" --parse --format markdown
```

Use `--transform` with GJSON syntax to extract specific fields:

```bash
nimble search --query "AI news" --transform "results.#.url"
```

## Commands

### search

Accurate, real-time web search with 8 focus modes. AI Agents search the live web to retrieve precise information. Run `nimble search --help` for all options.

**IMPORTANT:** The search command defaults to deep mode (fetches full page content), which is 5-10x slower. Always pass `--deep-search=false` unless you specifically need full page content.

Always explicitly set these parameters on every search call:

- `--deep-search=false`: **Pass this on every call** for fast responses (1-3s vs 5-15s). Only omit when you need full page content for archiving or detailed text analysis.
- `--include-answer`: **Recommended on every research/exploration query.** Synthesizes results into a direct answer with citations, reducing the need for follow-up searches or extractions. Only skip for URL-discovery-only queries where you just need links. **Note:** This is a premium feature (Enterprise plans). If the API returns a `402` or `403` when using this flag, retry the same query without `--include-answer` and continue — the search results are still valuable without the synthesized answer.
- `--topic`: Match to query type — `coding`, `news`, `academic`, etc. Default is `general`. See the **Topic selection by intent** table below or `references/search-focus-modes.md` for guidance.
- `--num-results`: Default `10` — balanced speed and coverage.

```bash
# Basic search (always include --deep-search=false)
nimble search --query "your query" --deep-search=false

# Coding-focused search
nimble search --query "React hooks tutorial" --topic coding --deep-search=false

# News search with time filter
nimble search --query "AI developments" --topic news --time-range week --deep-search=false

# Search with AI-generated answer summary
nimble search --query "what is WebAssembly" --include-answer --deep-search=false

# Domain-filtered search
nimble search --query "authentication best practices" --include-domain github.com --include-domain stackoverflow.com --deep-search=false

# Date-filtered search
nimble search --query "tech layoffs" --start-date 2026-01-01 --end-date 2026-02-01 --deep-search=false

# Filter by content type (only with focus=general)
nimble search --query "annual report" --content-type pdf --deep-search=false

# Control number of results
nimble search --query "Python tutorials" --num-results 15 --deep-search=false

# Deep search — ONLY when you need full page content (5-15s, much slower)
nimble search --query "machine learning" --deep-search --num-results 5
```

**Key options:**

| Flag | Description |
|------|-------------|
| `--query` | Search query string (required) |
| `--deep-search=false` | **Always pass this.** Disables full page content fetch for 5-10x faster responses |
| `--deep-search` | Enable full page content fetch (slow, 5-15s — only when needed) |
| `--topic` | Focus mode: general, coding, news, academic, shopping, social, geo, location |
| `--num-results` | Max results to return (default 10) |
| `--include-answer` | Generate AI answer summary from results |
| `--include-domain` | Only include results from these domains (repeatable, max 50) |
| `--exclude-domain` | Exclude results from these domains (repeatable, max 50) |
| `--time-range` | Recency filter: hour, day, week, month, year |
| `--start-date` | Filter results after this date (YYYY-MM-DD) |
| `--end-date` | Filter results before this date (YYYY-MM-DD) |
| `--content-type` | Filter by type: pdf, docx, xlsx, documents, spreadsheets, presentations |
| `--parsing-type` | Output format: markdown, plain_text, simplified_html |
| `--country` | Country code for localized results |
| `--locale` | Locale for language settings |
| `--max-subagents` | Max parallel subagents for shopping/social/geo modes (1-10, default 3) |

**Focus modes** (quick reference — for detailed per-mode guidance, decision tree, and combination strategies, **read `references/search-focus-modes.md`**):

| Mode | Best for |
|------|----------|
| `general` | Broad web searches (default) |
| `coding` | Programming docs, code examples, technical content |
| `news` | Current