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 search query "best pho in Saigon" --location "Vietnam" --language "en"

tinyfish search query "tinyfish web automation" --pretty

`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
`--per-url-timeout-ms <milliseconds>`	Per-URL timeout budget, from `1` to `110000` milliseconds
`--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 fetch content get "https://site-a.com" "https://site-b.com" "https://site-c.com"

tinyfish fetch content get --links --image-links "https://example.com"

tinyfish fetch content get --per-url-timeout-ms 45000 "https://example.com"

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

`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
`--output-schema <json>`	Inline JSON Schema object for structured output
`--output-schema-file <path>`	Path to a JSON file containing the output schema
`--browser-profile <profile>`	Browser profile for execution (`lite` or `stealth`)
`--max-steps <n>`	Maximum tool-call steps before stopping (`1`-`500`)
`--mode <mode>`	Agent behavior mode (`default` or `strict`). `strict` is in beta — join the beta to use it (contact support to enable it).
`--session-id <uuid>`	Caller-provided UUID for idempotency / parallel-safe `--sync`
`--use-vault`	Inject vault credentials into the run. Requires a connected vault provider.
`--credential-item-id <id>`	Scope the run to a specific credential item by `itemId` (repeat for multiple; from `tinyfish vault item list`). Requires `--use-vault`. Omit to use all enabled items.
`--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","timestamp":"2024-01-15T10:30:00Z"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Navigating to the pricing page","timestamp":"2024-01-15T10:30:02Z"}
{"type":"COMPLETE","run_id":"abc123","status":"COMPLETED","result":{"result":"{\"price\":\"£99.00\"}"},"run_url":"https://agent.tinyfish.ai/runs/abc123"}

The default stream also emits STREAMING_URL events (the live browser view) and periodic HEARTBEAT keep-alives.

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","error":null,"status":"PENDING","run_url":"https://agent.tinyfish.ai/runs/abc123"}

`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 list --status COMPLETED

tinyfish agent run list --limit 50 --cursor <cursor_from_previous_response>

tinyfish agent run list --pretty

`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 get abc123 --pretty

`tinyfish agent run steps <run_id>`

Print the step-by-step trace for a run.

tinyfish agent run steps abc123

Flags

Flag	Description
`--pretty`	Human-readable output

`tinyfish agent run watch <run_id>`

Poll a run and print new steps as they arrive. Exits when the run reaches a terminal status.

tinyfish agent run watch abc123

Flags

Flag	Description
`--timeout <ms>`	Stop polling after this many milliseconds (default `1800000`)
`--interval <ms>`	Poll interval (default `3000`, min `500`)
`--pretty`	Human-readable output

`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

tinyfish browser session create --url "https://example.com"

tinyfish browser session create --pretty

`tinyfish profile create`

Create a new Browser Context Profile.

tinyfish profile create --name "my-github"

Flags

Flag	Description
`--name <name>`	Profile name (required)
`--pretty`	Human-readable output

Output

{
  "id": "profile_abc123",
  "name": "my-github",
  "created_at": "2026-06-22T10:00:00Z"
}

Examples

tinyfish profile create --name "my-github"

tinyfish profile create --name "my-github" --pretty

`tinyfish profile import-cookies`

Extract cookies from your local Chrome install and upload them to a profile. This lets TinyFish reuse your existing logged-in session without you having to log in again during a run. Use --domain to import cookies for a single site, or --all-domains to import every domain in your Chrome profile in one shot. Exactly one of these flags must be provided — they are mutually exclusive.

tinyfish profile import-cookies --domain github.com

Supported on macOS and Linux. Requires Google Chrome to be installed.

Flags

Flag	Description
`--domain <domain>`	Domain to import cookies for, e.g. `github.com`. Mutually exclusive with `--all-domains`.
`--all-domains`	Import cookies for every domain in your Chrome profile. Mutually exclusive with `--domain`.
`--profile-id <id>`	Profile to import into. If omitted, a new profile is created automatically.
`--pretty`	Human-readable output

Output

{
  "cookie_count": 15,
  "domains_updated": ["github.com"]
}

Examples

tinyfish profile import-cookies --domain github.com

tinyfish profile import-cookies --domain github.com --profile-id profile_abc123

tinyfish profile import-cookies --all-domains

tinyfish profile import-cookies --domain github.com --pretty

After importing, pass the profile ID to tinyfish agent run via --use-profile or include use_profile: true + profile_id in your API request to reuse the session.

See Browser Context Profiles for the full workflow.

`tinyfish vault connection add`

Connect a credential provider (1Password or Bitwarden). Credentials are validated immediately — if they’re invalid, the command fails. Provider secrets are read from environment variables, never passed as flags, so they stay out of shell history.

# 1Password — service account token from env
TINYFISH_VAULT_TOKEN=ops_... \
  tinyfish vault connection add --provider 1password

# Bitwarden — client secret + master password from env; client ID is a flag
TINYFISH_VAULT_CLIENT_SECRET=<secret> TINYFISH_VAULT_MASTER_PASSWORD=<password> \
  tinyfish vault connection add --provider bitwarden --client-id user.xxxx-xxxx

Flags

Flag	Description
`--provider <provider>`	`1password` or `bitwarden` (required)
`--client-id <id>`	Bitwarden client ID (required for Bitwarden; format `user.xxxx-xxxx`)
`--server-url <url>`	Self-hosted Bitwarden server URL
`--pretty`	Human-readable output

Environment variables

Variable	Description
`TINYFISH_VAULT_TOKEN`	1Password service account token (starts with `ops_`)
`TINYFISH_VAULT_CLIENT_SECRET`	Bitwarden client secret
`TINYFISH_VAULT_MASTER_PASSWORD`	Bitwarden master password

`tinyfish vault connection list`

List all connected vault providers and their status.

tinyfish vault connection list

Flags

Flag	Description
`--pretty`	Human-readable output

`tinyfish vault connection remove <connectionId>`

Disconnect a provider. All cached credentials are removed immediately; runs already in progress are not affected.

tinyfish vault connection remove a1b2c3d4-5678-90ab-cdef-1234567890ab

Flags

Flag	Description
`--pretty`	Human-readable output

`tinyfish vault item sync`

Pull the latest credentials from all connected providers. Run this after adding new credentials or changing passwords in your vault.

tinyfish vault item sync

Flags

Flag	Description
`--pretty`	Human-readable output

`tinyfish vault item list`

List all synced credential items. Each item has an itemId — that’s what you pass to --credential-item-id on agent run.

tinyfish vault item list

{
  "items": [
    {
      "itemId": "cred:conn-123:Personal:item-abc123",
      "label": "GitHub Login",
      "vaultName": "Personal",
      "domains": ["github.com"],
      "hasTotp": false,
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
  ]
}

Flags

Flag	Description
`--pretty`	Human-readable output

Examples

# 1. Connect (one-time)
TINYFISH_VAULT_TOKEN=ops_... tinyfish vault connection add --provider 1password

# 2. List items (sync first if the list is empty)
tinyfish vault item sync
tinyfish vault item list --pretty

# 3. Run with credentials
tinyfish agent run "Log in and export the invoices" \
  --url https://example.com \
  --use-vault \
  --credential-item-id cred:conn-123:Personal:item-abc123

tinyfish agent run "Check my dashboard" --url https://example.com --use-vault

See Vault & Credentials for provider setup instructions and troubleshooting.

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

​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 steps <run_id>

​Flags

​tinyfish agent run watch <run_id>

​Flags

​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

​tinyfish profile create

​Flags

​Output

​Examples

​tinyfish profile import-cookies

​Flags

​Output

​Examples

​tinyfish vault connection add

​Flags

​Environment variables

​tinyfish vault connection list

​Flags

​tinyfish vault connection remove <connectionId>

​Flags

​tinyfish vault item sync

​Flags

​tinyfish vault item list

​Flags

​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 steps <run_id>`

Flags

`tinyfish agent run watch <run_id>`

Flags

`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

`tinyfish profile create`

Flags

Output

Examples

`tinyfish profile import-cookies`

Flags

Output

Examples

`tinyfish vault connection add`

Flags

Environment variables

`tinyfish vault connection list`

Flags

`tinyfish vault connection remove <connectionId>`

Flags

`tinyfish vault item sync`

Flags

`tinyfish vault item list`

Flags

Examples

Auth commands