CLI Commands - TinyFish Web Agent

`tinyfish search query`

Run a web search. Returns ranked results with titles, URLs, and snippets.

tinyfish search query "best React state management libraries"

Flags

Flag	Description
`--location <value>`	Location hint for geo-targeted results (e.g. `"Vietnam"`)
`--language <value>`	Language hint (e.g. `"en"`)
`--pretty`	Human-readable output

Output

{
  "query": "best React state management libraries",
  "total_results": 10,
  "results": [
    {
      "position": 1,
      "site_name": "Reddit",
      "title": "Best State Management for React in 2026",
      "url": "https://reddit.com/r/reactjs/...",
      "snippet": "Zustand and Jotai are the most popular choices..."
    }
  ]
}

Examples

tinyfish search query "tinyfish web automation"

`tinyfish fetch content get`

Fetch clean, extracted content from one or more URLs. Strips ads, navigation, and boilerplate — returns just the content.

tinyfish fetch content get "https://example.com/article"

Accepts up to 10 URLs in a single call. Multiple URLs are fetched in parallel server-side.

Flags

Flag	Description
`--format <format>`	Output format: `markdown` (default), `html`, or `json`
`--links`	Include extracted links from the page
`--image-links`	Include extracted image URLs
`--pretty`	Human-readable output

Output

{
  "results": [
    {
      "url": "https://example.com/article",
      "final_url": "https://example.com/article/",
      "title": "Article Title",
      "description": "A brief description",
      "language": "en",
      "author": "Jane Doe",
      "published_date": "2026-01-15",
      "format": "markdown",
      "text": "# Article Title\n\nThe full article content in clean markdown...",
      "latency_ms": 1430.39
    }
  ],
  "errors": []
}

When --links or --image-links are set, each result also includes:

{
  "links": ["https://example.com/about", "https://example.com/contact"],
  "image_links": ["https://example.com/hero.png"]
}

Examples

tinyfish fetch content get --format markdown "https://example.com/article"

`tinyfish agent run`

Execute a browser automation. By default the output streams as newline-delimited JSON — one object per event.

tinyfish agent run "goal" --url example.com

Flags

Flag	Description
`--url <url>`	Target URL to automate (required)
`--sync`	Wait for the run to complete and return the full result
`--async`	Submit only — return the `run_id` immediately without waiting
`--pretty`	Human-readable output instead of JSON

Output modes

Streaming (default)
Sync (--sync)
Async (--async)

One JSON object per line as events arrive. Use this when you want live progress or are piping to another tool.

tinyfish agent run "Extract the pricing" --url example.com/pricing

{"type":"STARTED","run_id":"abc123","run_url":"https://agent.tinyfish.ai/runs/abc123"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Navigating to the pricing page"}
{"type":"COMPLETE","run_id":"abc123","status":"COMPLETED","result":{"price":"$99"},"run_url":"https://agent.tinyfish.ai/runs/abc123"}

Pressing Ctrl+C during a streaming run cancels the run server-side before exiting.

Waits for the run to finish and returns a single JSON object with the full result. Use this for scripts where you only care about the final output.

tinyfish agent run "Extract the pricing" --url example.com/pricing --sync

{"run_id":"abc123","run_url":"https://agent.tinyfish.ai/runs/abc123","status":"COMPLETED","result":{"price":"$99"},"num_of_steps":4}

Submits the run and returns immediately with the run_id. Use this when you want to fire-and-forget or manage polling yourself.

tinyfish agent run "Extract the pricing" --url example.com/pricing --async

{"run_id":"abc123","run_url":"https://agent.tinyfish.ai/runs/abc123","error":null}

`tinyfish agent run list`

List recent runs.

tinyfish agent run list

Flags

Flag	Description
`--status <status>`	Filter by status: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, or `CANCELLED`
`--limit <n>`	Number of runs to return (default `20`, max `100`)
`--cursor <cursor>`	Pagination cursor from a previous response
`--pretty`	Human-readable output

Examples

tinyfish agent run list

`tinyfish agent run get <run_id>`

Get the full details of a specific run.

tinyfish agent run get abc123

Returns the complete run object including status, result, and metadata.

Flags

Flag	Description
`--pretty`	Human-readable output

Example

tinyfish agent run get abc123

`tinyfish agent run cancel <run_id>`

Cancel a run that is PENDING or RUNNING.

tinyfish agent run cancel abc123

{"run_id":"abc123","status":"CANCELLED","cancelled_at":"2024-01-15T10:30:00Z","message":null}

Flags

Flag	Description
`--pretty`	Human-readable output

`tinyfish agent batch run`

Submit a batch of runs from a CSV file. The CSV must have url and goal columns.

tinyfish agent batch run --input runs.csv

CSV format

url,goal
https://example.com,"Extract the main heading"
https://another.com,"Get the price and availability"

Flags

Flag	Description
`--input <file>`	Path to CSV file (required)
`--pretty`	Human-readable output

Output

{
  "data": {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "total": 2,
    "submitted": 2,
    "results_url": "https://agent.tinyfish.ai/runs"
  }
}

Batches are tracked locally in ~/.tinyfish/batches.json. Use batch list and batch get to check progress.

`tinyfish agent batch list`

List all locally tracked batches.

tinyfish agent batch list

Flags

Flag	Description
`--pretty`	Human-readable output

Output

[
  {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "run_ids": ["run-1", "run-2"],
    "total": 2,
    "submitted": 2,
    "created_at": "2026-04-10T10:30:00Z"
  }
]

`tinyfish agent batch get <batch_id>`

Get run results for a batch, including per-run status and extracted data.

tinyfish agent batch get 550e8400-e29b-41d4-a716-446655440000

Flags

Flag	Description
`--pretty`	Human-readable output

Output

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "run_id": "run-1",
      "status": "COMPLETED",
      "goal": "Extract the main heading",
      "num_of_steps": 5,
      "result": { "heading": "Welcome" }
    }
  ],
  "not_found": null
}

`tinyfish agent batch cancel <batch_id>`

Cancel all runs in a batch.

tinyfish agent batch cancel 550e8400-e29b-41d4-a716-446655440000

Flags

Flag	Description
`--pretty`	Human-readable output

Output

{
  "results": [
    {
      "run_id": "run-1",
      "status": "CANCELLED",
      "cancelled_at": "2026-04-10T10:35:00Z",
      "message": null
    }
  ],
  "not_found": null
}

`tinyfish browser session create`

Spin up a remote browser instance. Returns a CDP (Chrome DevTools Protocol) WebSocket URL for programmatic control.

tinyfish browser session create

Flags

Flag	Description
`--url <url>`	Navigate to a URL after session creation
`--pretty`	Human-readable output

Output

{
  "session_id": "tf-9c669a12-a0d3-456e-8126-6524c32f10fc",
  "cdp_url": "wss://ip-13-56-193-1.tetra-data.production.tinyfish.io/tf-9c669a12-a0d3-456e-8126-6524c32f10fc",
  "base_url": "https://ip-13-56-193-1.tetra-data.production.tinyfish.io/tf-9c669a12-a0d3-456e-8126-6524c32f10fc"
}

Use the cdp_url to connect with Playwright, Puppeteer, or any CDP-compatible client. The base_url can be used for HTTP-based interactions with the session.

Examples

tinyfish browser session create

Auth commands

Command	Description
`tinyfish auth login`	Open the API keys page and save a key interactively
`tinyfish auth set`	Read an API key from stdin and save it
`tinyfish auth status`	Check whether a key is configured and where it comes from
`tinyfish auth logout`	Remove the saved API key

Start Here

Agent API

Search API

Fetch API

Browser API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

​tinyfish search query

​Flags

​Output

​Examples

​tinyfish fetch content get

​Flags

​Output

​Examples

​tinyfish agent run

​Flags

​Output modes

​tinyfish agent run list

​Flags

​Examples

​tinyfish agent run get <run_id>

​Flags

​Example

​tinyfish agent run cancel <run_id>

​Flags

​tinyfish agent batch run

​CSV format

​Flags

​Output

​tinyfish agent batch list

​Flags

​Output

​tinyfish agent batch get <batch_id>

​Flags

​Output

​tinyfish agent batch cancel <batch_id>

​Flags

​Output

​tinyfish browser session create

​Flags

​Output

​Examples

​Auth commands

`tinyfish search query`

Flags

Output

Examples

`tinyfish fetch content get`

Flags

Output

Examples

`tinyfish agent run`

Flags

Output modes

`tinyfish agent run list`

Flags

Examples

`tinyfish agent run get <run_id>`

Flags

Example

`tinyfish agent run cancel <run_id>`

Flags

`tinyfish agent batch run`

CSV format

Flags

Output

`tinyfish agent batch list`

Flags

Output

`tinyfish agent batch get <batch_id>`

Flags

Output

`tinyfish agent batch cancel <batch_id>`

Flags

Output

`tinyfish browser session create`

Flags

Output

Examples

Auth commands