tinyfish-cli

name	tinyfish-cli
description	Use when searching the web, fetching/extracting page content, running natural-language browser automations, or creating remote CDP browser sessions from the terminal via the TinyFish CLI (cli-anything-tinyfish). API-key auth, JSON output, no browser OAuth.
version	0.1.1
author	Jason Brashear (@webdevtodayjason)
license	MIT

TinyFish CLI (cli-anything-tinyfish)

Agent-native CLI over the TinyFish Web Agent REST APIs. All four TinyFish products, one binary: search the web, fetch clean page content, run natural-language browser automations, and create remote browser sessions for direct CDP control. Everything prints JSON to stdout (errors are JSON on stderr, exit 1), so output is directly parseable — no scraping of human-formatted text.

Setup

pip install cli-anything-tinyfish
export TINYFISH_API_KEY="sk-tinyfish-..."   # free key: https://agent.tinyfish.ai/api-keys
cli-anything-tinyfish auth status            # {"authenticated": true, ...}

Search and fetch are credit-free. Agent runs consume TinyFish credits.

Choosing the right command

1. search — you need URLs/snippets for a topic you don't have sources for.
2. fetch — you already know the URL(s) and want the content (JS-rendered, boilerplate stripped). Up to 10 URLs per call, fetched in parallel.
3. run — the task needs interaction: clicking, forms, multi-step flows. Prefer search/fetch when reading alone is enough — runs are slower and cost credits.
4. browser create — you need direct browser control from your own code (Playwright/Puppeteer/CDP): returns a remote session's cdp_url to connect to. Prefer run when a plain-English goal is enough.

Commands

# Web search (ranked results: title, url, snippet)
cli-anything-tinyfish search "best raspberry pi 5 cooling" --location US

# Fetch one or many URLs as clean markdown (html/json also available)
cli-anything-tinyfish fetch https://example.com/article --format markdown
cli-anything-tinyfish fetch https://a.com https://b.com --links --ttl 0   # ttl 0 = live fetch

# Browser automation in plain English (sync — waits for the result)
cli-anything-tinyfish run "Extract the pricing table as JSON" --url https://example.com/pricing

# Fire-and-forget automation, then poll
cli-anything-tinyfish run "Download the latest invoice" --url https://app.example.com --submit
cli-anything-tinyfish runs get <run_id>
cli-anything-tinyfish runs list --status RUNNING
cli-anything-tinyfish runs cancel <run_id>      # async-submitted runs only

# Remote browser session for direct Playwright/Puppeteer/CDP control
cli-anything-tinyfish browser create --url https://example.com
# → {"session_id": "tf-…", "cdp_url": "wss://…", "base_url": "https://…"}
# e.g. Playwright: chromium.connect_over_cdp(cdp_url)

Add --pretty to any command for indented output when a human is reading.

Output contract

• stdout: one JSON document per invocation (the API response, unmodified).
• stderr: {"error": "...", "status": <http-code>?, "detail": ...} on failure.
• exit code: 0 success, 1 failure (including missing TINYFISH_API_KEY).

Notes for agents

• Per-URL fetch failures land in the response's errors[] next to a 200 — check it before assuming all URLs succeeded.
• Sync run is not cancellable; use --submit when you may need runs cancel.
• Write automation goals like instructions to a junior operator: name the exact output you want ("Return JSON with fields price, plan_name").