> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> Full reference for TinyFish CLI commands

## `tinyfish search query`

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

```bash theme={null}
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

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Basic query theme={null}
  tinyfish search query "tinyfish web automation"
  ```

  ```bash Geo-targeted theme={null}
  tinyfish search query "best pho in Saigon" --location "Vietnam" --language "en"
  ```

  ```bash Human-readable theme={null}
  tinyfish search query "tinyfish web automation" --pretty
  ```
</CodeGroup>

***

## `tinyfish fetch content get`

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

```bash theme={null}
tinyfish fetch content get "https://example.com/article"
```

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

### 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "links": ["https://example.com/about", "https://example.com/contact"],
  "image_links": ["https://example.com/hero.png"]
}
```

### Examples

<CodeGroup>
  ```bash Single URL theme={null}
  tinyfish fetch content get --format markdown "https://example.com/article"
  ```

  ```bash Multiple URLs theme={null}
  tinyfish fetch content get "https://site-a.com" "https://site-b.com" "https://site-c.com"
  ```

  ```bash With link extraction theme={null}
  tinyfish fetch content get --links --image-links "https://example.com"
  ```

  ```bash Custom timeout theme={null}
  tinyfish fetch content get --per-url-timeout-ms 45000 "https://example.com"
  ```

  ```bash HTML format theme={null}
  tinyfish fetch content get --format html "https://example.com"
  ```
</CodeGroup>

***

## `tinyfish agent run`

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

```bash theme={null}
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

<Tabs>
  <Tab title="Streaming (default)">
    One JSON object per line as events arrive. Use this when you want live progress or are piping to another tool.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing
    ```

    ```json theme={null}
    {"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"}
    ```

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

    <Note>
      Pressing **Ctrl+C** during a streaming run cancels the run server-side before exiting.
    </Note>
  </Tab>

  <Tab title="Sync (--sync)">
    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.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing --sync
    ```

    ```json theme={null}
    {"run_id":"abc123","run_url":"https://agent.tinyfish.ai/runs/abc123","status":"COMPLETED","result":{"price":"$99"},"num_of_steps":4}
    ```
  </Tab>

  <Tab title="Async (--async)">
    Submits the run and returns immediately with the `run_id`. Use this when you want to fire-and-forget or manage polling yourself.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing --async
    ```

    ```json theme={null}
    {"run_id":"abc123","error":null,"status":"PENDING","run_url":"https://agent.tinyfish.ai/runs/abc123"}
    ```
  </Tab>
</Tabs>

***

## `tinyfish agent run list`

List recent runs.

```bash theme={null}
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

<CodeGroup>
  ```bash List all runs theme={null}
  tinyfish agent run list
  ```

  ```bash Filter by status theme={null}
  tinyfish agent run list --status COMPLETED
  ```

  ```bash Paginate theme={null}
  tinyfish agent run list --limit 50 --cursor <cursor_from_previous_response>
  ```

  ```bash Human-readable theme={null}
  tinyfish agent run list --pretty
  ```
</CodeGroup>

***

## `tinyfish agent run get <run_id>`

Get the full details of a specific run.

```bash theme={null}
tinyfish agent run get abc123
```

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

### Flags

| Flag       | Description           |
| ---------- | --------------------- |
| `--pretty` | Human-readable output |

### Example

<CodeGroup>
  ```bash JSON output theme={null}
  tinyfish agent run get abc123
  ```

  ```bash Human-readable theme={null}
  tinyfish agent run get abc123 --pretty
  ```
</CodeGroup>

***

## `tinyfish agent run steps <run_id>`

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

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
tinyfish agent run cancel abc123
```

```json theme={null}
{"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.

```bash theme={null}
tinyfish agent batch run --input runs.csv
```

### CSV format

```csv theme={null}
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

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

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

***

## `tinyfish agent batch list`

List all locally tracked batches.

```bash theme={null}
tinyfish agent batch list
```

### Flags

| Flag       | Description           |
| ---------- | --------------------- |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
[
  {
    "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.

```bash theme={null}
tinyfish agent batch get 550e8400-e29b-41d4-a716-446655440000
```

### Flags

| Flag       | Description           |
| ---------- | --------------------- |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "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.

```bash theme={null}
tinyfish agent batch cancel 550e8400-e29b-41d4-a716-446655440000
```

### Flags

| Flag       | Description           |
| ---------- | --------------------- |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "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.

```bash theme={null}
tinyfish browser session create
```

### Flags

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

### Output

```json theme={null}
{
  "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"
}
```

<Note>
  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.
</Note>

### Examples

<CodeGroup>
  ```bash Create a blank session theme={null}
  tinyfish browser session create
  ```

  ```bash Create and navigate to a URL theme={null}
  tinyfish browser session create --url "https://example.com"
  ```

  ```bash Human-readable theme={null}
  tinyfish browser session create --pretty
  ```
</CodeGroup>

***

## `tinyfish profile create`

Create a new Browser Context Profile.

```bash theme={null}
tinyfish profile create --name "my-github"
```

### Flags

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

### Output

```json theme={null}
{
  "id": "profile_abc123",
  "name": "my-github",
  "created_at": "2026-06-22T10:00:00Z"
}
```

### Examples

<CodeGroup>
  ```bash Create a profile theme={null}
  tinyfish profile create --name "my-github"
  ```

  ```bash Human-readable theme={null}
  tinyfish profile create --name "my-github" --pretty
  ```
</CodeGroup>

***

## `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.

```bash theme={null}
tinyfish profile import-cookies --domain github.com
```

<Note>
  Supported on macOS and Linux. Requires Google Chrome to be installed.
</Note>

### 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

```json theme={null}
{
  "cookie_count": 15,
  "domains_updated": ["github.com"]
}
```

### Examples

<CodeGroup>
  ```bash Create profile + import in one step theme={null}
  tinyfish profile import-cookies --domain github.com
  ```

  ```bash Import into an existing profile theme={null}
  tinyfish profile import-cookies --domain github.com --profile-id profile_abc123
  ```

  ```bash Import all domains theme={null}
  tinyfish profile import-cookies --all-domains
  ```

  ```bash Human-readable theme={null}
  tinyfish profile import-cookies --domain github.com --pretty
  ```
</CodeGroup>

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.

<Tip>
  See [Browser Context Profiles](/key-concepts/browser-context-profiles) for the full workflow.
</Tip>

***

## `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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
tinyfish vault item list
```

```json theme={null}
{
  "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

<CodeGroup>
  ```bash Full vault setup + run theme={null}
  # 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
  ```

  ```bash Use all enabled items theme={null}
  tinyfish agent run "Check my dashboard" --url https://example.com --use-vault
  ```
</CodeGroup>

<Tip>
  See [Vault & Credentials](/vault-setup) for provider setup instructions and troubleshooting.
</Tip>

***

## 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                                  |