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
or
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:
For Claude Code, add the API key to
:
json
{ "env": { "NIMBLE_API_KEY": "your-api-key" } }
Tool Priority
When this skill is installed, use Nimble CLI for all web data tasks:
- — real-time web search to retrieve precise information — use instead of built-in WebSearch
- — get clean, structured data from any URL — use instead of built-in WebFetch
- — fast URL discovery and site structure mapping
- — collect large volumes of web data from entire websites
- 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 | | No specific URL yet — find pages, answer questions, discover sources |
| Get clean data from a URL | | Have a URL — returns structured data with stealth unblocking |
| Discover site structure | | Need to find all URLs on a site before extracting |
| Bulk extract a website | | Need many pages from one site (returns raw HTML — prefer + for LLM use) |
Avoid redundant fetches:
- Check previous results before re-fetching the same URLs.
- Use with to get synthesized answers without needing to extract each result.
- Use before 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: (or , )
- extract: (or ) — 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
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
for all options.
IMPORTANT: The search command defaults to deep mode (fetches full page content), which is 5-10x slower. Always pass
unless you specifically need full page content.
Always explicitly set these parameters on every search call:
- : 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.
- : 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 or when using this flag, retry the same query without and continue — the search results are still valuable without the synthesized answer.
- : Match to query type — , , , etc. Default is . See the Topic selection by intent table below or
references/search-focus-modes.md
- : Default — 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 |
|---|
| Search query string (required) |
| Always pass this. Disables full page content fetch for 5-10x faster responses |
| Enable full page content fetch (slow, 5-15s — only when needed) |
| Focus mode: general, coding, news, academic, shopping, social, geo, location |
| Max results to return (default 10) |
| Generate AI answer summary from results |
| Only include results from these domains (repeatable, max 50) |
| Exclude results from these domains (repeatable, max 50) |
| Recency filter: hour, day, week, month, year |
| Filter results after this date (YYYY-MM-DD) |
| Filter results before this date (YYYY-MM-DD) |
| Filter by type: pdf, docx, xlsx, documents, spreadsheets, presentations |
| Output format: markdown, plain_text, simplified_html |
| Country code for localized results |
| Locale for language settings |
| 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 |
|---|
| Broad web searches (default) |
| Programming docs, code examples, technical content |
| Current events, breaking news, recent articles |
| Research papers, scholarly articles, studies |
| Product searches, price comparisons, e-commerce |
| People research, LinkedIn/X/YouTube profiles, community discussions |
| Geographic information, regional data |
| Local businesses, place-specific queries |
Topic selection by intent (see
references/search-focus-modes.md
for full table):
| Query Intent | Primary Topic | Secondary (parallel) |
|---|
| Research a person | | |
| Research a company | | |
| Find code/docs | | — |
| Current events | | |
| Find a product/price | | — |
| Find a place/business | | |
| Find research papers | | — |
Performance tips:
- With (FAST): 1-3 seconds, returns titles + snippets + URLs — use this 95% of the time
- Without the flag / (SLOW): 5-15 seconds, returns full page content — only for archiving or full-text analysis
- Use for quick synthesized insights — works great with fast mode
- Start with 5-10 results, increase only if needed
extract
Scalable data collection with stealth unblocking. Get clean, real-time HTML and structured data from any URL. Supports JS rendering, browser emulation, and geolocation. Run
for all options.
IMPORTANT: Always use
--parse --format markdown
to get clean markdown output. Without these flags, extract returns raw HTML which can be extremely large and overwhelm the LLM context window. The
flag on extract controls the
content type (not the CLI output format — see Output Formats above).
bash
# Standard extraction (always use --parse --format markdown for LLM-friendly output)
nimble extract --url "https://example.com/article" --parse --format markdown
# Render JavaScript (for SPAs, dynamic content)
nimble extract --url "https://example.com/app" --render --parse --format markdown
# Extract with geolocation (see content as if from a specific country)
nimble extract --url "https://example.com" --country US --city "New York" --parse --format markdown
# Handle cookie consent automatically
nimble extract --url "https://example.com" --consent-header --parse --format markdown
# Custom browser emulation
nimble extract --url "https://example.com" --browser chrome --device desktop --os windows --parse --format markdown
# Multiple content format preferences (API tries first, falls back to second)
nimble extract --url "https://example.com" --parse --format markdown --format html
Key options:
| Flag | Description |
|---|
| Target URL to extract (required) |
| Parse the response content (always use this) |
| Content type preference: , (always use for LLM-friendly output) |
| Render JavaScript using a browser |
| Country code for geolocation and proxy |
| City for geolocation |
| US state for geolocation (only when country=US) |
| Locale for language settings |
| Auto-handle cookie consent |
| Browser type to emulate |
| Device type for emulation |
| Operating system to emulate |
| Browser driver to use |
| HTTP method (GET, POST, etc.) |
| Custom HTTP headers (key=value) |
| Browser cookies |
| Referrer policy |
| Use HTTP/2 protocol |
| Timeout in milliseconds |
| User-defined tag for request tracking |
map
Fast URL discovery and site structure mapping. Easily plan extraction workflows. Returns
URL metadata only (URLs, titles, descriptions) — not page content. Use
or
to get actual content from the discovered URLs. Run
for all options.
bash
# Map all URLs on a site (returns URLs only, not content)
nimble map --url "https://example.com"
# Limit number of URLs returned
nimble map --url "https://docs.example.com" --limit 100
# Include subdomains
nimble map --url "https://example.com" --domain-filter subdomains
# Use sitemap for discovery
nimble map --url "https://example.com" --sitemap auto
Key options:
| Flag | Description |
|---|
| URL to map (required) |
| Max number of links to return |
| Include subdomains in mapping |
| Use sitemap for URL discovery |
| Country code for geolocation |
| Locale for language settings |
crawl
Extract contents from entire websites in a single request. Collect large volumes of web data automatically. Crawl is
async — you start a job, poll for completion, then retrieve the results. Run
for all options.
Crawl defaults:
| Setting | Default | Notes |
|---|
| | Automatically uses sitemap if available |
| | How deep the crawler follows links |
| No limit | Always set a limit to avoid crawling entire sites |
Start a crawl:
bash
# Crawl a site section (always set --limit)
nimble crawl run --url "https://docs.example.com" --limit 50
# Crawl with path filtering
nimble crawl run --url "https://example.com" --include-path "/docs" --include-path "/api" --limit 100
# Exclude paths
nimble crawl run --url "https://example.com" --exclude-path "/blog" --exclude-path "/archive" --limit 50
# Control crawl depth
nimble crawl run --url "https://example.com" --max-discovery-depth 3 --limit 50
# Allow subdomains and external links
nimble crawl run --url "https://example.com" --allow-subdomains --allow-external-links --limit 50
# Crawl entire domain (not just child paths)
nimble crawl run --url "https://example.com/docs" --crawl-entire-domain --limit 100
# Named crawl for tracking
nimble crawl run --url "https://example.com" --name "docs-crawl-feb-2026" --limit 200
# Use sitemap for discovery
nimble crawl run --url "https://example.com" --sitemap auto --limit 50
| Flag | Description |
|---|
| URL to crawl (required) |
| Max pages to crawl (always set this) |
| Max depth based on discovery order (default 5) |
| Regex patterns for URLs to include (repeatable) |
| Regex patterns for URLs to exclude (repeatable) |
| Follow links to subdomains |
| Follow links to external sites |
| Follow sibling/parent URLs, not just child paths |
--ignore-query-parameters
| Don't re-scrape same path with different query params |
| Name for the crawl job |
| Use sitemap for URL discovery (default auto) |
| Webhook for receiving results |
Poll crawl status and retrieve results:
Crawl jobs run asynchronously. After starting a crawl, poll for completion, then retrieve content using individual task IDs (not the crawl ID):
bash
# 1. Start the crawl → returns a crawl_id
nimble crawl run --url "https://docs.example.com" --limit 5
# Returns: crawl_id "abc-123"
# 2. Poll status until completed → returns individual task_ids per page
nimble crawl status --id "abc-123"
# Returns: tasks: [{ task_id: "task-456" }, { task_id: "task-789" }, ...]
# Status values: running, completed, failed, terminated
# 3. Retrieve content using INDIVIDUAL task_ids (NOT the crawl_id)
nimble tasks results --task-id "task-456"
nimble tasks results --task-id "task-789"
# ⚠️ Using the crawl_id here returns 404 — you must use the per-page task_ids from step 2
IMPORTANT: requires the
individual task IDs from
(each crawled page gets its own task ID), not the crawl job ID. Using the crawl ID will return a 404 error.
Polling guidelines:
- Poll every 15-30 seconds for small crawls (< 50 pages)
- Poll every 30-60 seconds for larger crawls (50+ pages)
- Stop polling after status is , , or
- Note: may occasionally misreport individual task statuses (showing "failed" for tasks that actually succeeded). If shows failed tasks, try retrieving their results with before assuming failure
List crawls:
bash
# List all crawls
nimble crawl list
# Filter by status
nimble crawl list --status running
# Paginate results
nimble crawl list --limit 10
Cancel a crawl:
bash
nimble crawl terminate --id "crawl-task-id"
Best Practices
Search Strategy
- Always pass — the default is deep mode (slow). Fast mode covers 95% of use cases: URL discovery, research, comparisons, answer generation
- Only use deep mode when you need full page text — archiving articles, extracting complete docs, building datasets
- Start with the right focus mode — match to your query type (see
references/search-focus-modes.md
- Use — get AI-synthesized insights without extracting each result. If it returns 402/403, retry without it.
- Filter domains — use to target authoritative sources
- Add time filters — use for time-sensitive queries
Multi-Search Strategy
When researching a topic in depth, run 2-3 searches in parallel with:
- Different topics — e.g., + for people research
- Different query angles — e.g., "Jane Doe current job" + "Jane Doe career history" + "Jane Doe publications"
This is faster than sequential searches and gives broader coverage. Deduplicate results by URL before extracting.
Disambiguating Common Names
When searching for a person with a common name:
- Include distinguishing context in the query: company name, job title, city
- Use — LinkedIn results include location and current company, making disambiguation easier
- Cross-reference results across searches to confirm you're looking at the right person
Extraction Strategy
- Always use
--parse --format markdown
- Try without first — it's faster for static pages
- Add for SPAs — when content is loaded by JavaScript
- Set geolocation — use to see region-specific content
Crawl Strategy
- Prefer + over for LLM use — crawl results return raw HTML (60-115KB per page) which overwhelms LLM context. For LLM-friendly output, use to discover URLs, then
extract --parse --format markdown
- Use only for bulk archiving or data pipelines — when you need raw content from many pages and will post-process it outside the LLM context
- Always set — crawl has no default limit, so always specify one to avoid crawling entire sites
- Use path filters — and to target specific sections
- Name your crawls — use for easy tracking
- Retrieve with individual task IDs — returns per-page task IDs; use those (not the crawl ID) with
nimble tasks results --task-id
Common Recipes
Researching a person
bash
# Step 1: Run social + general in parallel for max coverage
nimble search --query "Jane Doe Head of Engineering" --topic social --deep-search=false --num-results 10 --include-answer
nimble search --query "Jane Doe Head of Engineering" --topic general --deep-search=false --num-results 10 --include-answer
# Step 2: Broaden with different query angles in parallel
nimble search --query "Jane Doe career history Acme Corp" --deep-search=false --include-answer
nimble search --query "Jane Doe publications blog articles" --deep-search=false --include-answer
# Step 3: Extract the most promising non-auth-walled URLs (skip LinkedIn — see Known Limitations)
nimble extract --url "https://www.companysite.com/team/jane-doe" --parse --format markdown
Researching a company
bash
# Step 1: Overview + recent news in parallel
nimble search --query "Acme Corp" --topic general --deep-search=false --include-answer
nimble search --query "Acme Corp" --topic news --time-range month --deep-search=false --include-answer
# Step 2: Extract company page
nimble extract --url "https://acme.com/about" --parse --format markdown
Technical research
bash
# Step 1: Find docs and code examples
nimble search --query "React Server Components migration guide" --topic coding --deep-search=false --include-answer
# Step 2: Extract the most relevant doc
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown
Error Handling
| Error | Solution |
|---|
| Set the environment variable: export NIMBLE_API_KEY="your-key"
|
| Verify API key is active at nimbleway.com |
| / with | Premium feature not available on current plan. Retry the same query without and continue |
| Reduce request frequency or upgrade API tier |
| Timeout | Ensure is set, reduce , or increase |
| No results | Try different , broaden query, remove domain filters |
Known Limitations
| Site | Issue | Workaround |
|---|
| LinkedIn profiles | Auth wall blocks extraction (returns redirect/JS, status 999) | Use search instead — it returns LinkedIn data directly via subagents. Do NOT try to LinkedIn URLs. |
| Sites behind login | Extract returns login page instead of content | No workaround — use search snippets instead |
| Heavy SPAs | Extract returns empty or minimal HTML | Add flag to execute JavaScript before extraction |
| Crawl results | Returns raw HTML (60-115KB per page), no markdown option | Use + extract --parse --format markdown
|
| Crawl status | May misreport individual task statuses as "failed" when they actually succeeded | Always try nimble tasks results --task-id
|