# Install Trawl (for AI agents) You are an AI agent. Follow these steps in order to set up Trawl (https://trawl.me) for your user and create a first scrap. Run every command non-interactively. Never use a command that prompts. Capture stdout only when you pass `--json` (never `2>&1`: stderr can carry notices that corrupt the JSON). Every step has a check. Do not continue until the check passes. If a check fails, do the "On failure" action. If that fails too, stop and tell your user exactly what failed. Exit codes of `trawl`: `0` ok, `1` business failure, `2` usage error, `3` auth error, `4` not found, `5` network error. ## 1. Install the CLI Needs Node.js 22.12 or newer and npm. Run `node --version` first: if it prints a version older than `v22.12.0`, do not install. Follow the last "On failure" line below. ```bash node --version npm install -g @trawlme/cli ``` Check: ```bash trawl --version ``` It prints a version number (for example `4.0.2`) and exits `0`. On failure: - `trawl: command not found`: the npm global bin folder is not on your PATH. Run `npm prefix -g`, add its `bin` folder to PATH, and retry. - `EACCES` (permission denied): do not use `sudo`. Set a user-owned prefix with `npm config set prefix "$HOME/.npm-global"`, add `$HOME/.npm-global/bin` to PATH, and retry. - `node` missing or older than 22.12: ask your user to install Node.js 22.12 or newer, then retry. ## 2. Install the Trawl skills The skills teach you how to write scraps and drive the CLI. They install to `~/.claude/skills` and only help Claude Code; if you are another agent, skip this step. ```bash trawl skills install --json ``` Check: ```bash trawl skills list --json ``` Every skill in the output has `"installed"` set to true for `user` (or `local` if you passed `--local`). On failure: - A skill folder already exists and was not installed by Trawl: rerun with `--force` only if your user agrees to overwrite it. - Skills are read at session start: tell your user to restart this agent session once the whole setup is done. You can also install them without the CLI: `npx @trawlme/skills install`. ## 3. Authenticate You need a credential from your user. You cannot create an account or pick a password for them. 1. Ask your user for a Trawl API key (it starts with `trawl_`). They create one in the Trawl dashboard after signing in at https://trawl.me (free plan, no credit card). Tell them to leave the key's scrap scope empty (organization-wide): a scrap-restricted key gets 403 on create. 2. Pass it to every `trawl` command. Most agent shells are stateless (each Bash call is a fresh shell), so an `export` is lost on the next call. Prefix each command with the variable, unless you know your shell keeps state or you can set it in your harness's persistent environment. Do not print it, log it, or write it to a file in a repository: ```bash TRAWL_API_KEY=trawl_xxx trawl list --json ``` Use that prefix on every `trawl` command in steps 4 and 5 too. Check: ```bash TRAWL_API_KEY=trawl_xxx trawl ping --json TRAWL_API_KEY=trawl_xxx trawl list --json ``` `trawl ping` returns a JSON status and exits `0`, but it never authenticates: only `trawl list` proves the key works. `trawl list` returns a JSON array (empty `[]` on a new account) and exits `0`. An exit `3` means the credential is missing, invalid or expired. On failure: - Exit `3` (`"kind":"auth"`): first check the variable is still set for this command (a stateless shell loses it); add the prefix and retry. Only if it was set, the key is wrong or revoked: ask your user for a new one. - Exit `5` (`"kind":"network"`): the API is unreachable. Check the network, then retry. If `ping` keeps failing, stop and report it. - Your user has no key but has an email and password: they can run `trawl login` themselves in a terminal. Do not ask them to paste a password to you. - If your user gives you a session JWT instead of a key: prefix commands with `TRAWL_TOKEN=` the same way. `TRAWL_API_KEY` wins when both are set. ## 4. Health check There is no `trawl doctor` command. The health check is the pair from step 3 plus the version: ```bash trawl --version TRAWL_API_KEY=trawl_xxx trawl ping --json TRAWL_API_KEY=trawl_xxx trawl list --json ``` All three must exit `0`. (`trawl scraps doctor ` diagnoses one scrap after a run, see step 6.) ## 5. Create the first scrap Ask your user for a public URL and what to extract, in plain language. Then: ```bash TRAWL_API_KEY=trawl_xxx trawl create "https://example.com" --prompt "Extract the page title and the main paragraph" --json ``` This takes 30 to 250 seconds or more: Trawl writes the scrap with AI, saves it and runs it once. Do not interrupt it: set your command timeout to at least 5 minutes (many harnesses stop a command after 2 minutes by default). If your harness kills it anyway, treat it as exit `5` below. Check: exit `0` and the JSON payload has `success: true`. The scrap id is `scrap._id`. Then read the data: ```bash TRAWL_API_KEY=trawl_xxx trawl data --json ``` It returns a JSON array of items (not empty for a page with content). While the run is still going, `data` exits `1` with an `in_progress` status: wait a minute and retry, do not treat it as a final failure. On failure: - Exit `1` also covers API errors, so read stdout first: - stdout is `{"error": ...}` (for example `"kind":"api"` with status 403 scope or 429 quota): no scrap exists. Report the status and message to your user and stop. - stdout is a payload with `success: false` and no `scrap`: nothing was persisted. Report the message to your user and stop. - stdout is a payload with `success: false` and a `scrap`: the scrap was created (`scrap._id`) but its first run failed. AI auto-fix retries in the background. Wait a minute, then run `trawl scraps doctor --json` and `trawl data --json`. Report what the doctor says. - Exit `5` (timeout): the scrap may already exist. Run `trawl list --json` and look for it before retrying. A blind retry makes a duplicate and spends quota twice. - Exit `2`: a flag or the URL is wrong. The URL must start with `http://` or `https://`. - Exit `3`: go back to step 3 (check the key is passed on this command). Note: the new scrap re-runs every day at 07:00 UTC by default. Tell your user. To stop or change it: `trawl scraps update --no-cron`. ## 6. Report to your user Tell your user, in a few lines: - The CLI version installed and that `trawl ping` works. - The scrap id and the first items returned. - That the scrap runs daily, and the command to stop it. - That they should restart this agent session so the skills load. ## Reference - CLI on npm: https://www.npmjs.com/package/@trawlme/cli - `trawl spec --json` prints the exact machine-readable command tree of the installed version. - Docs: https://trawl.me/docs