The Trawl CLI in 10 Minutes: Create a Scraper, Run It, Read the Data

Install the Trawl CLI, create a scraper from one sentence, run it and read the rows as JSON. Real output from version 3.17.0, what each command costs, and how to script it with exit codes.

Trawl banner: tutorial, cli, quickstart

Four commands take you from an empty terminal to JSON you can pipe into anything: install, log in, create a scraper from one sentence, read its data. This is the whole loop with the Trawl command line, tested on version 4.0.4, with the output we actually got and the three defaults worth knowing before you automate anything.

Here is the shortest version, so you know where this ends:

npm install -g @trawlme/cli
trawl login
trawl create https://www.scrapethissite.com/pages/simple/ \
  --prompt "Every country on the page: name, capital, population \
and area in square km."
trawl data <id> --json | jq '.[0]'

The rest of the article explains what each line did, what it cost, and how to script it safely.

A terminal running trawl create on a country list page, from the progress lines to the saved scrap id and the Next step line
trawl create from one sentence, with the wait sped up. Demo account, scrapethissite.com.

What you need

Node 22.12 or newer, and a Trawl account. The free plan gives you 10,000 compute once, with no card. Compute is what the AI spends writing the scraper and what each run spends afterwards, so keep an eye on it: building the scraper for the page below cost about 4,700 in our latest test (it varies with the page, and more on large or protected pages), and every run after that costs about 50 to 100. The practice page below, Scrape This Site, lists countries and is a public page built for this kind of test.

If you have no account yet, sign up on trawl.me and verify your email first. If you would rather not use a terminal, the web app builds the same kind of scraper from one sentence, and the try page shows that flow with no account.

Install and log in

npm install -g @trawlme/cli
trawl --version
trawl login

The package is @trawlme/cli. Every output below comes from version 4.0.4. Version 4 needs Node 22.12 or newer, so update Node first if npm install complains. trawl login asks for your email and password, stores a session token on your machine, and, in an interactive terminal, also installs the Claude Code skills bundled with the CLI. If you use Claude Code, restart it afterwards so it sees them.

Check that you are in:

$ trawl whoami
Alex Demo
  ID:       6ad9...e0f4
  Provider: local
  Roles:    user

(The email line is left out here.)

Signed up with Google or Apple, so there is no password to type? Skip login and use an API key instead: create one under Developers, API Keys in the app (available on every plan, Free included), then export it as TRAWL_API_KEY. The commands in this article that create, run and read scrapers accept a key. Commands that change a scraper afterwards, such as trawl scraps update, and whoami need a session login, as the README explains.

Create a scraper from a sentence

trawl create https://www.scrapethissite.com/pages/simple/ \
  --prompt "Every country on the page: name, capital, population \
and area in square km."

Write the prompt like a sentence to a colleague: the thing you want a row for, the fields in each row, and where it lives. There is no selector to write. Trawl opens the page in a real browser, writes the script, tests it against the live page, and saves it. It took 88 seconds on our first try and 46 on the latest one. The terminal ended with:

  Probing the site
  Probing the site (tier tier0)
  Reading the page
  Writing the script
  Checking the script
  Testing the script (attempt 1 of 6)
✓ Scrapethissite
  Scrap ID:   6ada12ee7cd82f05269813aa
  Run ID:     6ada12ef7cd82f05269815fd
  First run:  succeeded
  Schedule:   weekly Monday 07:00 UTC (cron 0 7 * * 1)
  Sample:     250 items
  Fields:     name, capital, population, area_km2
  name      : Andorra
  Next step:  trawl data 6ada12ee7cd82f05269813aa
              (details: trawl get 6ada12ee7cd82f05269813aa)

(The prompt is split over two lines, and the last line of the output is wrapped, only to fit the page.) A scrap is Trawl's word for one saved scraper: its script, its data and its schedule. Copy the Scrap ID, every other command takes it. The scraper name is derived from the host, which is why ours is called "Scrapethissite".

What create sets up for you

The summary above does not list three defaults that come with every scraper made this way.

  • It scheduled itself. The command has no schedule flag. A scraper created from the CLI runs every Monday at 07:00 UTC (the web wizard uses your browser's timezone instead). Runs spend compute wherever they start from, about 50 to 100 each on a simple page. Change it with trawl scraps update <id> --cron "0 9 * * 1", or switch it off with --no-cron.
  • It turned the digest on. After the first run, Trawl turns on an email summary addressed to your account email. It goes out after each later run, the weekly one and the ones you start by hand. A sent digest costs roughly 100 to 650 compute depending on how much data it summarizes, and a digest with no change costs nothing. Opt out when you create with --no-digest, or later with trawl scraps update <id> --no-digest.
  • Auto-fix is on. If the site changes its layout and the scraper breaks, Trawl tries to repair it. Self-healing scrapers explains how. create also has a --no-autofix flag, which its help text describes as turning auto-fix off when the first run fails.

We checked all three on the scraper above: trawl get shows the cron, and the scrap's settings show autoFix: true and a digest addressed to the account email.

The retry trap: list before you retry

create is not idempotent. If your Wi-Fi drops, or a gateway answers 502 or 504 after the work has started, the CLI exits with an error while Trawl carries on creating the scraper and running it. A blind retry then builds a second copy and pays for the AI step twice.

Two things protect you. First, Trawl refuses an identical request: the same organization, the same URL and the same sentence within about 15 minutes. Here is what we got when we ran our own command again:

$ trawl create https://www.scrapethissite.com/pages/simple/ \
    --prompt "Every country on the page: name, capital, \
population and area in square km."
✗ A scrap for this URL and goal was already created a few minutes ago
  (existing scrap id: 6ada12ee7cd82f05269813aa). Use that scrap instead of
  creating another.
$ echo $?
1

It costs nothing and hands you the id of the first one. Second, your own habit: after any network error on create, run trawl list and look for your URL before you try again. Change the wording of the sentence and the 15-minute guard no longer applies, because it is a different request.

Run it and read the data

Everything above ran the scraper once. To run it again on demand:

$ trawl run 6ada12ee7cd82f05269813aa
Scrap 6ada12ee7cd82f05269813aa run complete

run blocks until the run is finished, then prints one line and exits with 0 when the run worked. The run itself took about 30 seconds in our test, and the time varies with the site and the load. A run costs about 50 to 100 compute on a simple page. To launch a run and get your prompt back immediately, use trawl trigger <id> instead.

Reading is a different matter. trawl data returns the last saved run. It is read-only and spends nothing, so you can call it as often as you like:

$ trawl data 6ada12ee7cd82f05269813aa
Last run data:
  Items: 250
  First item keys: name, capital, population, area_km2
  Use --json for full output.

The human output is a summary. Add --json for the rows themselves, as a plain array on standard output. Each row is one country with four fields, and the numbers come as real numbers, not strings. The first one looks like this:

{
  "name": "Andorra",
  "capital": "Andorra la Vella",
  "population": 84000,
  "area_km2": 468
}

From here it is ordinary shell. This line prints the three most populated countries:

trawl data 6ada12ee7cd82f05269813aa --json \
  | jq -r 'sort_by(-.population) | .[:3][] | "\(.name): \(.population)"'
China: 1330044000
India: 1173108018
United States: 310232863

Swap the filter for jq -r '.[] | [.name, .capital, .population] | @csv' and you have a CSV, as in the picture below.

A terminal showing trawl data piped through jq into four CSV lines with country, capital and population
The saved rows as CSV, straight from the terminal. Demo account.

Two more read commands tell you how the scraper is doing. trawl runs <id> lists past runs, newest first (the real output also has two columns that stay empty on a healthy run, failureKind and blockType, left out here):

hid                       status   time   tier   createdAt
6ada13277cd82f0526982456  success  28259  tier0  2026-10-22T13:44:07.525Z
6ada12ef7cd82f05269815fd  success  35566  tier0  2026-10-22T13:43:11.065Z

The time column is in milliseconds. A retry loop that only checks the exit code never learns why the last run failed, so read the diagnosis first: trawl scraps doctor <id> reports the status of the last run, whether the site blocked it, and the proxy tier used. On a healthy scraper it is short:

Scrapethissite  ● success (success)
  Run ID:  6ada13277cd82f0526982456
  Blocked: no
  Proxy:   Tier 0
  Run at:  22/10/26 15:44

Note the spelling: doctor lives under scraps, there is no top-level trawl doctor. For the reasons a run can fail, see what Trawl 3.2 added.

The same scraper, in the app

A CLI scrap is the same object as a web one. Open Scraps in the app and it is in your list with its data and schedule, and what you change in one place shows in the other.

The scraper workspace Data tab listing countries with name, capital, population and area columns, 1 to 50 of 250
The scraper created from the terminal, open in the app: 250 rows, four columns. Demo account.

Script it: exit codes and JSON errors

Every command takes --json. With it, nothing prompts, and a failure prints one error object on standard output:

{
  "error": {
    "message": "404 Not Found: No Scrap with that identifier ...",
    "status": 404,
    "kind": "not_found",
    "retryable": false
  }
}

(Printed on one line by the CLI, formatted here.)

Branch on kind and retryable, not on the message text. The exit code carries the same information, and we triggered each of these for real:

Exit codeMeaningWhat we ran to get it
0Successtrawl data <id> --json
1Generic error or a refusalthe duplicate create above
2Usage errortrawl list --nope, or an id that is not 24 hex characters
3Not logged in or token expiredtrawl list with no credentials
4Not foundtrawl data 000000000000000000000000
5Network errortrawl list against an address nobody listens on

Only the network error comes back with "retryable": true. For create, even that comes with the warning from the previous section: check the list first.

In a script or a CI job, skip login and pass a credential through the environment, as TRAWL_API_KEY for a key or TRAWL_TOKEN for a session token. For a job that needs no human, the key is the better fit, and the keys can be limited to specific scrapers. To keep the CLI from reporting anonymous usage, set TRAWL_TELEMETRY=0 or run trawl telemetry off.

A small example, a job that fails loudly when the last run has no rows:

#!/usr/bin/env bash
set -euo pipefail
rows=$(trawl data "$SCRAP_ID" --json | jq length)
[ "$rows" -gt 0 ] || { echo "no rows"; exit 1; }
echo "$rows rows"

Because set -e is on, a failing trawl data stops the script with its own exit code, so a missing scrap or an expired token never looks like a good run.

Cheat sheet

GoalCommandCosts compute
Create a scrapertrawl create <url> --prompt "..."Yes, the biggest bill
List scraperstrawl listNo
Show a scrapertrawl get <id>No
Run now and waittrawl run <id>About 50 to 100
Run without waitingtrawl trigger <id>About 50 to 100
Read the last datatrawl data <id> --jsonNo
Past runstrawl runs <id>No
Why a run went wrongtrawl scraps doctor <id>No
Change or stop the scheduletrawl scraps update <id> --cron "..." or --no-cronNo
Want to try it on a page of your own? Start free on Trawl, 10,000 free compute and no card.

Where to go next

You now have a scraper that lives on Trawl's side, runs on a schedule and answers to a one-line command. The natural next move is to put it to work: have an assistant read the same data through the Trawl MCP endpoint, which takes a Bearer token such as the API key above, or run your scrapers from a CI pipeline using the exit codes you just saw. If a run ever fails, start with trawl scraps doctor, then the post on why a run failed.

Ready to build your own? Create your first scrap on Trawl and point the CLI at a page you care about.

Disclaimer: Trawl provides scraping infrastructure. Users are responsible for ensuring their use complies with applicable laws and website terms of service. This article is for educational purposes only.

Written by Pierre | November 2026