TinyFish CLI
You have access to the TinyFish CLI (tinyfish) — a suite of web tools you can call from the terminal.
If not installed: npm install -g @tiny-fish/cli
If not authenticated: tinyfish auth login --source openclaw or set TINYFISH_API_KEY env var.
When This Skill Should Trigger
Use TinyFish whenever a request depends on live web information or page content. Do not wait for the user to say "TinyFish" or "scrape".
Strong triggers include:
- Search or discovery: search, find, look up, research, compare, latest, current, news, docs, pricing, product details, best options.
- URL/page reading: fetch, read, summarize, extract from this page, inspect this URL, get the content, pull links or metadata.
- Source-backed answers: answer using web sources, verify a fact, check whether something changed, gather information from the web.
- Website work: interact with a site, click through pages, fill forms, log in, collect structured data, handle bot-protected pages.
Default to the lightest tool that can answer:
- No URL and the user needs web information:
search, thenfetchthe best result(s) if more detail is needed. - URL provided and only content is needed:
fetch. - Page interaction or dynamic extraction is needed:
agent. - Raw CDP/Playwright-style control is needed:
browser.
Picking the Right Tool
TinyFish has four tools. Start with the lightest one that can do the job and escalate only when needed.
search → fetch → agent → browser lightest heaviest
| Tool | When to use | Speed | Cost |
|---|---|---|---|
| search | You need to find URLs, current facts, docs, pricing, product details, or a quick source-backed answer | Fastest | Lowest |
| fetch | You have URLs and need clean page content, summaries, article text, docs, product pages, links, or metadata | Fast | Low |
| agent | You need to interact with a page — click, fill forms, navigate, extract structured data from dynamic sites | Slower | Higher |
| browser | Agent isn't enough — you need raw programmatic browser control via CDP | Slowest | Highest |
Common Patterns
Research: search → fetch Search for a topic, then fetch the best results to read their full content.
bash# 1. Find URLs tinyfish search query "best React state management libraries 2026" # 2. Read the top results tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"
Deep extraction: search → agent Search to find the right site, then use agent to interact with it and extract structured data.
bash# 1. Find the site tinyfish search query "Nike running shoes official store" # 2. Automate extraction on it tinyfish agent run --url "https://nike.com/running" \ "Extract all running shoes as JSON: [{\"name\": str, \"price\": str, \"colors\": [str]}]"
Escalation: fetch → agent Try fetch first. If the page is dynamic/JS-heavy and fetch returns empty or incomplete content, escalate to agent.
Full control: agent → browser If agent can't handle a complex multi-step workflow, spin up a raw browser session and automate it yourself via CDP.
Commands
tinyfish search query
Web search. Returns ranked results with titles, URLs, and snippets.
bashtinyfish search query "<query>" [--location <hint>] [--language <hint>] [--pretty]
- Returns 10 results by default
- Use
--locationand--languagefor geo-targeted results - Default output is JSON;
--prettyfor human-readable
bashtinyfish search query "best pho in Ho Chi Minh City" --location "Vietnam" --language "en"
tinyfish fetch content get
Fetch clean, extracted content from one or more URLs. Strips ads, nav, boilerplate — returns just the content.
bashtinyfish fetch content get <urls...> [--format markdown|html|json] [--links] [--image-links] [--pretty]
- Accepts multiple URLs in a single call — they are fetched in parallel server-side
--format markdown(default) — clean readable text--format json— structured document tree--links— include all extracted links from the page--image-links— include extracted image URLs- Response includes:
url,final_url,title,language,author,published_date,text,latency_ms
bash# Fetch one page as markdown tinyfish fetch content get --format markdown "https://example.com/article" # Fetch multiple pages with links tinyfish fetch content get --links "https://site-a.com" "https://site-b.com" "https://site-c.com"
tinyfish agent run
Run a browser automation using a natural language goal. The agent opens a real browser, navigates, clicks, fills forms, and extracts data.
bashtinyfish agent run --url <url> "<goal>" [--sync] [--async] [--pretty]
| Flag | Purpose |
|---|---|
--url <url> | Target URL (bare hostnames get https:// auto-prepended) |
--sync | Wait for full result without streaming steps |
--async | Submit and return immediately |
--pretty | Human-readable output |
Output: Default streams data: {...} SSE lines. The final result is the event where type == "COMPLETE" and status == "COMPLETED" — the extracted data is in the resultJson field. Read the raw output directly; no script-side parsing is needed.
Always specify the JSON structure you want in the goal:
bashtinyfish agent run --url "https://example.com/products" \ "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]" tinyfish agent run --url "https://example.com/search" \ "Search for 'wireless headphones', filter under $50, extract top 5 as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"
Parallel extraction — when hitting multiple independent sites, make separate calls. Do NOT combine into one goal.
Good — parallel calls (run simultaneously):
bashtinyfish agent run --url "https://pizzahut.com" \ "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]" tinyfish agent run --url "https://dominos.com" \ "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"
Bad — single combined call:
bash# Don't do this — less reliable and slower tinyfish agent run --url "https://pizzahut.com" \ "Extract prices from Pizza Hut and also go to Dominos..."
Managing runs:
bashtinyfish agent run list [--status PENDING|RUNNING|COMPLETED|FAILED|CANCELLED] [--limit N] tinyfish agent run get <run_id> tinyfish agent run cancel <run_id>
Batch operations — submit many runs from a CSV file (url,goal columns):
bashtinyfish agent batch run --input runs.csv tinyfish agent batch list tinyfish agent batch get <batch_id> tinyfish agent batch cancel <batch_id>
tinyfish browser session create
Spin up a remote browser instance. Returns a CDP WebSocket URL for programmatic control.
bashtinyfish browser session create [--url <url>] [--pretty]
--urloptionally navigates to a page after creation- Returns
session_id,cdp_url(WebSocket), andbase_url - Use the
cdp_urlwith Playwright, Puppeteer, or any CDP client
bashtinyfish browser session create --url "https://example.com" # Returns: { session_id, cdp_url: "wss://...", base_url: "https://..." }
General Notes
- Match the user's language: Respond in whatever language the user writes in.
- All commands support
--prettyfor human-readable output. Default is JSON. - Use
--debugon the root command or setTINYFISH_DEBUG=1to log HTTP requests to stderr.
