use-tinyfish

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TinyFish — Web Extraction & Automation via CLI

TinyFish — 基于CLI的网页提取与自动化工具

You have access to the TinyFish CLI (

tinyfish

), a tool that runs browser automations from the terminal using natural language goals.

你可以使用TinyFish CLI（

tinyfish

），这是一款通过自然语言目标指令在终端中运行浏览器自动化任务的工具。

Pre-flight Check (REQUIRED)

前置检查（必填）

Before making any TinyFish call, always run BOTH checks:

1. CLI installed?

bash

which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"

If not installed, stop and tell the user:

Install the TinyFish CLI:
npm install -g @tiny-fish/cli

2. Authenticated?

bash

tinyfish auth status

If not authenticated, stop and tell the user:

You need a TinyFish API key. Get one at: https://agent.tinyfish.ai/api-keys

Then authenticate:

Option 1 — CLI login (interactive):
tinyfish auth login
Option 2 — Environment variable (CI/CD):
export TINYFISH_API_KEY="your-key-here"
Option 3 — Claude Code settings: Add to
~/.claude/settings.local.json
:
json
{
  "env": {
    "TINYFISH_API_KEY": "your-key-here"
  }
}

Do NOT proceed until both checks pass.

在调用任何TinyFish命令之前，请务必完成以下两项检查：

1. 是否已安装CLI？

bash

which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"

如果未安装，请停止操作并告知用户：

安装TinyFish CLI：
npm install -g @tiny-fish/cli

2. 是否已完成身份验证？

bash

tinyfish auth status

如果未验证，请停止操作并告知用户：

你需要一个TinyFish API密钥。请访问以下地址获取：https://agent.tinyfish.ai/api-keys

然后进行身份验证：

选项1 — CLI交互式登录：
tinyfish auth login
选项2 — 环境变量（适用于CI/CD场景）：
export TINYFISH_API_KEY="your-key-here"
选项3 — Claude Code设置： 添加至
~/.claude/settings.local.json
：
json
{
  "env": {
    "TINYFISH_API_KEY": "your-key-here"
  }
}

必须在两项检查都通过后才能继续操作。

Core Command

核心命令

bash

tinyfish agent run --url <url> "<goal>"

bash

tinyfish agent run --url <url> "<goal>"

Flags

命令参数

Flag	Purpose
`--url <url>`	Target website URL
`--sync`	Wait for full result (no streaming)
`--async`	Submit and return immediately
`--pretty`	Human-readable formatted output

Default behavior streams SSE step-by-step progress as JSON to stdout.

参数	用途
`--url <url>`	目标网站的URL
`--sync`	等待完整结果返回（非流式输出）
`--async`	提交任务后立即返回
`--pretty`	输出人类易读的格式化内容

默认行为是将SSE分步进度以JSON格式流式输出至标准输出。

Best Practices

最佳实践

Specify JSON format in the goal: Always describe the exact structure you want returned.
Parallel calls: When extracting from multiple independent sites, make separate parallel CLI calls instead of combining into one goal.
Match the user's language: Respond in whatever language the user is writing in.

在目标指令中指定JSON格式：请始终明确描述你期望返回的数据结构。
并行调用：当需要从多个独立站点提取数据时，请发起多个独立的CLI并行调用，而非将所有任务合并为一个目标指令。
匹配用户语言：使用用户所使用的语言进行响应。

Usage Patterns

使用场景示例

Basic Extract / Scrape

基础提取/爬取

Extract data from a page. Specify the JSON structure you want:

bash

tinyfish agent run --url "https://example.com" \
  "Extract product info as JSON: {\"name\": str, \"price\": str, \"in_stock\": bool}"

提取页面中的数据，请指定期望的JSON结构：

bash

tinyfish agent run --url "https://example.com" \
  "Extract product info as JSON: {\"name\": str, \"price\": str, \"in_stock\": bool}"

Multiple Items

多条目提取

Extract lists of data with explicit structure:

bash

tinyfish agent run --url "https://example.com/products" \
  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"

提取列表数据并指定明确结构：

bash

tinyfish agent run --url "https://example.com/products" \
  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"

Multi-Step Automation

多步骤自动化

For tasks that require interaction (clicking, filling forms, navigating):

bash

tinyfish agent run --url "https://example.com/search" \
  "Search for 'wireless headphones', apply filter for price under $50, extract the top 5 results as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"

适用于需要交互操作的任务（如点击、填写表单、页面导航）：

bash

tinyfish agent run --url "https://example.com/search" \
  "Search for 'wireless headphones', apply filter for price under $50, extract the top 5 results as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"

Sync Mode (Wait for Full Result)

同步模式（等待完整结果）

When you need the complete result before proceeding:

bash

tinyfish agent run --sync --url "https://example.com" \
  "Extract the main heading and page description as JSON: {\"heading\": str, \"description\": str}"

当你需要获取完整结果后再继续后续操作时使用：

bash

tinyfish agent run --sync --url "https://example.com" \
  "Extract the main heading and page description as JSON: {\"heading\": str, \"description\": str}"

Pretty Output

格式化输出

For human-readable output when presenting directly to the user:

bash

tinyfish agent run --pretty --url "https://example.com" \
  "Extract all navigation links as JSON: [{\"text\": str, \"href\": str}]"

当需要向用户展示易读的结果时使用：

bash

tinyfish agent run --pretty --url "https://example.com" \
  "Extract all navigation links as JSON: [{\"text\": str, \"href\": str}]"

Parallel Extraction

并行提取

When extracting from multiple independent sources, make separate parallel CLI calls. Do NOT combine into one goal.

Good — Parallel calls (run these simultaneously):

bash

tinyfish 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

undefined

当从多个独立源提取数据时，请发起多个独立的CLI并行调用，不要将所有任务合并为一个目标指令。

推荐方式 — 并行调用（可同时运行）：

bash

tinyfish 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}]"

不推荐方式 — 单一合并调用：

bash

undefined

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..."


Each independent extraction task should be its own CLI call. This is faster (parallel execution) and more reliable.

---

tinyfish agent run --url "https://pizzahut.com"
"Extract prices from Pizza Hut and also go to Dominos..."


每个独立的提取任务都应作为单独的CLI调用。这样速度更快（并行执行）且可靠性更高。

---

Output

输出结果

The CLI streams

data: {...}

SSE lines by default. 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.

默认情况下，CLI会以

data: {...}

的SSE行格式流式输出。最终结果是

type == "COMPLETE"

且

status == "COMPLETED"

的事件，提取的数据位于

resultJson

字段中。直接读取原始输出即可，无需在脚本端进行解析。

Managing Runs

任务管理

bash

undefined

bash

undefined

List recent runs

列出最近的任务

tinyfish agent run list

Get a specific run by ID

通过ID获取特定任务详情

tinyfish agent run get <run_id>

Cancel a running automation

取消正在运行的自动化任务

tinyfish agent run cancel <run_id>

undefined

tinyfish agent run cancel <run_id>

undefined