treg

# treg: the tool catalog for your agent **Ask for the job, not the tool.** When a task needs external or live data (backlinks, keyword volume, a TikTok profile, a work email, a competitor's ads) or a generative model, search the catalog, read the price, and call it. One token reaches two kinds of tool, and treg injects the credential on the server, so you never hold it: - **The catalog**: curated tools treg calls for you, each by id. - **Your own tools**: API accounts, OAuth connections, vendor CLIs and skills a teammate registered for the team. Never billed, with one exception: an X connection made through treg's own X app is billed per call, because X bills the app owner; the answer reports the price. ## First: check where you stand How treg reached you decides the first step. Take the first case that holds; either the MCP tools or the CLI is enough, and having both is fine. 1. **You can see treg's MCP tools** (`catalog_search`, `catalog_get`, `call`, `balance`, `my_tools`): treg is connected. Use them and install nothing; every `treg` command on this page maps onto a tool (see "Over MCP" below). A tool that answers "not authenticated" means the human signs in through the app's MCP or connector settings (in Claude Code: `/mcp`, pick treg, Authenticate). 2. **`treg` runs in your terminal**: run `treg`. It prints the account, the active team and your role, the balance, the team's own tools and the next commands to run; a blocker (not signed in, no team, an empty balance) comes first in its `help` lines. Not signed in: ```bash treg login # browser sign-in: GitHub, Google or an emailed code treg login --email you@company.com # an emailed 6-digit code treg login --token <team-token> # non-interactive, for agents and CI ``` 3. **Neither**: treg is not set up here. Run the installer only when the human asked you to set treg up; otherwise give them these two ways and wait: ```bash curl -fsSL {BASE}/install.sh | sh # the CLI, plus this skill for every agent it detects treg login ``` or, in an app that takes MCP servers, add `{BASE}/mcp/` and sign in when it asks. Given a team token, `curl -fsSL {BASE}/install.sh | sh -s -- --token <token>` does the install and sign-in at once. Everything runs in the **active team**. Invites arrive by email: `treg invites` lists them, `treg accept` takes one (or `treg org join <code>`); `treg org use <slug>` switches teams. A new verified account gets $1.00 of credit once, on its first eligible team; aliases of one inbox (`+tag`, Gmail dots) share it. **Over MCP** (`{BASE}/mcp/`), tools replace the CLI, and everything here maps onto them: - search the catalog → `catalog_search`, then `catalog_get` for the exact parameters and price. On `verdict: none`, file `catalog_request` rather than rephrasing. - what is new → `catalog_search` with `added_within_days` (30 is a good default) or `sort: "newest"`; `query` may then be empty. - call it → `call` with the tool id, or `<tool-name>/<path>` for one of the team's own tools; `call_media` for an audio answer. - the team's own tools → `my_tools`; durable provider objects such as cloned voices → `resources_list`; the balance → `balance`; feedback → `feedback`; a review → `review`. ## Find a tool and call it ```bash treg catalog search "subreddit posts" # tools that do the job, with prices treg catalog search --new # added in the last 30 days, newest first treg catalog get scrapecreators.reddit.subreddit.posts # parameters, price, a ready call line treg call scrapecreators.reddit.subreddit.posts --query subreddit=news treg catalog request "<what you need>" # searched and it is not there: file it ``` <!--hub--> **Six jobs are already built as tools. Call the tool, not the chain.** Each is one call on `{BASE}/call/<id>`, runs its steps in parallel, returns one fixed shape whichever provider answered, and charges its fee only for what it delivered. Chaining the parts yourself costs the same provider money and more calls. | you want | call | instead of, by hand | |---|---|---| | the people at a company, each with a checked email | `treg-hub.lead-pipeline` `{company_domain, title?, limit?, include_phone?}` | people.search, then email.find and email.verify per person | | one person's email, found and checked | `treg-hub.verified-email` `{linkedin_url}` or `{full_name, domain}` | email.find, then email.verify | | whether AI engines mention a brand | `treg-hub.ai-visibility` `{prompt, brand, brand_domain?, competitors?}` | ChatGPT, Gemini, Copilot and AI Mode one by one | | company details you can trust | `treg-hub.company-consensus` `{domain}` | two or three companies.enrich providers, compared | | how strong a site is in Google | `treg-hub.domain-authority` `{domain}` | backlinks summary, ranked keywords, linking domains | | a Search Console property's health (the team's own account) | `treg-hub.search-console-health` `{site}` | performance, sitemaps, URL inspection | `catalog_get <id>` shows each one's inputs, output and price. <!--/hub--> <!--routed--> **For a common job, call the routed tool, not a provider you remember.** Scraping a page (`treg.web.extract`), web search (`treg.web.search`), Google results (`treg.google.serp.organic`, `treg.google.serp.maps`), finding or verifying an email (`treg.people.email.find`, `treg.people.email.verify`) and most social profiles have a `treg.<capability>` tool. treg picks the provider (the team's own key first, then the cheapest per hit), moves on when one fails or misses, and bills only the answer it returns. The provider you used last week may not be the best one today. Name a provider only when you need fields or options only it has. How a routed call works: - POST what you know about the subject, e.g. `{full_name, domain}`, `{first_name, last_name, domain}` or `{linkedin_url}`. The answer is `{output, raw, _treg: {served_by, tried, charged_micro}}`, with `X-Treg-Served-By` naming the provider. - An error or a miss falls through to the next provider, cheapest first, within `X-Treg-Route-Max-Cost` (default $1 per call). A miss can be billed, which is why a routed tool quotes `usd_per_call: null` rather than $0: set the header for bulk runs. `X-Treg-Route-Waterfall: 0` stops at the first miss. - A filter the serving provider could not apply is named in `X-Treg-Ignored-Filters` and `_treg.ignored_filters`: filter the rows yourself, or send `X-Treg-Route-Strict-Filters: 1` to be refused with an unbilled 422 instead. - An asynchronous provider is polled for up to 60 seconds. If it is still running you get HTTP 202 with `_treg.outcome: pending`, its poll descriptor, `reserved_micro` and `charged_micro: null`. Do not retry or start another provider: the task may still finish and charge. - `catalog_get` on a routed id shows the ranked plan and its prices before you spend. **A found contact is not a confirmed one.** An email or phone find returns the provider's best match. Only `output.verified: true` means the mailbox was checked; otherwise `_treg.advice` names the verify step. Run it before anyone sends, and never re-send the same find: every hit is billed, repeats included. - Send `X-Treg-Route-Verify: true` on `treg.people.email.find`, `treg.people.email.find.personal` or `treg.people.phone.find` to check each hit in the same call, as its own small charge. Read `_treg.verification.verdict` and follow `_treg.advice`. A live phone line does not prove the number is this person's. <!--hub--> - `treg-hub.verified-email` finds and verifies in one call, and bills its fee only for a usable email. <!--/hub--> - **Verify every address before it is sent to**, including rows from a company or domain search (`treg.people.search` and the like): those are directory listings, unconfirmed unless the row's own verification field says otherwise. `invalid` is dead, `accept_all` is risky, and an address the provider did not return (`info@` after an empty domain search) is a guess, not a result. <!--/routed--> **Choosing between providers of one job.** `treg catalog get <id>` lists every provider of the same job with `COST`, `WORKS` (the success rate treg observed, with its sample size), `SPEED` (median) and `LAST OK`. Work down this order: 1. **The inputs you actually hold.** A tool that wants a `profile_url` is no substitute when you have a name and a domain, whatever it costs. 2. **Reliability.** A high `WORKS` on a real sample beats a rounder number on a tiny one: `99% (121)` is stronger evidence than `100% (8)`. 3. **Price.** Spreads inside one job reach 200×, so this is usually where the money is. 4. **`LAST OK`** breaks ties. A bare age means a real call came back; a `✓` age is the catalog's own verification stamp, not live traffic; `—` means nobody has verified or called it. After a 429, a 5xx or a timeout, switch to the next provider and say which. **Never retry a 4xx elsewhere:** it is almost always your request, and retrying spends money on several providers for one mistake. treg does not switch providers on a direct call; only you know which inputs you hold. **More on searching.** - Search for the job and for any output you need: `treg catalog search "email verification catch-all"` finds different tools from a broad email-verification search. When you need a provider-specific field (catch-all, disposable, role address, SMTP), call that provider's tool: the routed `treg.people.email.verify` defines only `valid`, `status` and `score`. - Discovery jobs usually come in two shapes: structured (filters such as title, location, followers, funding) and semantic (describe what you want). When a brief mixes hard limits with a fuzzy niche, run one tool of each shape and merge the results. - A tool marked `strict_query: true` accepts only its declared query parameters, once each, with required fields and allowed values enforced, and no body. Rejected input is not forwarded. **How a catalog call is served**, in this order: 1. the team registered its own tool for that provider: that tool and its key; 2. the team stored a key for the provider: that key; 3. neither, and the tool has a verified public route: no key, free; 4. otherwise treg's own account, billed to the team's balance. Connecting a key the team already pays for takes those calls off the balance. A free public route stays free only while you send no provider credential header yourself. A tool with no published price is refused, not served free: connect the team's own key. A few providers that sell only subscriptions carry a per-call rate treg set; `catalog get` says whose price it is. A team admin can pin a job to one provider (`treg org pin`), and then calls to the job's other providers are refused. **Calling well.** - **A JSON body from a file:** `treg call <id> --data @body.json` (`@-` reads stdin). On Windows PowerShell prefer it to inline JSON, whose inner quotes PowerShell strips. - **Scripting many calls:** use `treg --json call …`. Stdout is then one line, `{"result": <provider body>, "_treg": {"http_status", "call_id", "charged_micro"}}`, and nothing goes to stderr, so a script that merges the streams still parses every answer. `--await` is the exception: it prints the raw final response and writes progress to stderr, so keep the streams apart when you wait on a generation task. Run a handful and check the parsed results before looping over the whole list: a parse bug throws away answers that were already paid for. - **Calling in parallel is fine**, within limits: treg sets no per-token or per-team concurrency limit, and provider rate limits are relayed as they are. Where treg's own account for a provider is at its limit of calls in progress, a team that already has calls running on it gets 429 `share_busy`: send fewer at once, or call the routed tool, which moves on by itself. - **Over raw HTTP**, if a body carrying SQL or HTML is refused with an HTML 403 page by the hosting edge before treg sees it, base64-encode the body and add `X-Treg-Body-Encoding: base64` (also `gzip` or `base64+gzip`). The CLI does this by itself. ## Money **Call at the listed price without asking, then report what it cost.** Prices are visible before a call (`treg catalog get`, MCP `catalog_get`) and most are fractions of a cent. Before a generation task or a loop over many inputs, tell the human the expected total, then keep a running sum of `X-Treg-Cost-Micro` and stop before it passes what they agreed to. `X-Treg-Route-Max-Cost` caps each call, not the loop. - **Read the `cost` block, not only the headline.** `per_call` is flat. `type: per_result` with `unit: row` is priced per returned row, and its `~$/call` figure assumes a 20-row page (your `limit` sets the real count). `unit: target`, `domain` or `keyword` is priced per thing you ask about: one unit per target whatever the page size, so a body listing ten domains reserves ten. - **What you were charged** is the response header `X-Treg-Cost-Micro` (integer micro-USD; `cost_usd` over MCP), never anything in the provider's body. Keep `X-Treg-Call-Id` with it: it is the id to quote, and `GET {BASE}/calls/<call id>/result` returns the stored answer of a successful catalog call you lost. The CLI prints `treg: charged $<usd> · call id <id>` on stderr; stdout is always the exact body. On an asynchronous submission (a generation task) the header is the **reserved** amount, not a charge: the task settles the real one when it succeeds and refunds it all when it fails, so report it as reserved until the task is done. - **A hard ceiling per call:** `X-Treg-Route-Max-Cost: <usd>` refuses a call whose reservation would exceed it (402 `route_max_cost`, nothing charged). Where the catalog says the provider accepts a ceiling parameter, treg also forwards the remaining ceiling upstream, so a provider that fails over to a dearer source cannot settle above it; a refusal from that parameter is a non-2xx and costs nothing. For every other provider the header stays a pre-reservation guard. It applies to each request on its own and does not add up across calls. Direct calls have no default; on a routed call it also bounds the whole waterfall, $1 by default, and each child receives the unspent remainder. - **Failed calls are free.** A 4xx or 5xx relayed from the provider costs nothing. Empty results mean whatever the provider means by them; treg relays and does not normalise. A provider that reports a failure inside a 2xx (a DataForSEO task status other than 20000) is flagged with `X-Treg-Upstream-Failed` (`upstream_failed` over MCP): the body has no result, and the charge is what the provider billed for the attempt. - **Repeat questions are cheaper.** An answer may come from treg's archive of the same question (`X-Treg-Cache: hit`): the team's first call on a question costs full price, later hits 10%, and hits on the team's own key nothing. `Cache-Control: no-cache` forces a live call. - **A "free" tool can still bill** when treg's own account for its provider runs out and the call is relayed (`X-Treg-Served-Via: overflow:<name>`): if `catalog_get` shows `overflow_price_usd`, quote that price. - `treg balance` shows the balance and recent charges, and the dashboard's Activity page shows the settled cost of every call. `treg topup` adds funds or sets up automatic top-ups. ## When a call fails treg's own refusals carry the header `X-Treg-Error: 1` (`whose_error: treg` over MCP); without it, the status and body are the provider's. The CLI names whose answer it was on stderr. A bare 5xx with no JSON `detail` is never treg's. | you see | charged | what to do | |---|---|---| | a 4xx from the provider, other than 429 | no | Fix your request. Do not retry it with another provider. | | a 429 or 5xx from the provider | no | Try the next provider of the job, and say which. | | a timeout or dropped connection on your side | maybe | The provider may have answered and been paid. Repeat with the same `Idempotency-Key`; see below. | | 403 `capability_pinned` | no | A team admin pinned this job to one provider. Call `use_endpoint` from the body instead. | | 402 `insufficient_balance` | no | The body has `balance_micro`, `estimated_cost_micro`, `topup_url`. Check `treg balance`, then top up (`treg topup`, or the dashboard's Team → Billing) or connect the team's own key for that provider. | | 402 `route_max_cost` | no | Your `X-Treg-Route-Max-Cost` refused it. Ask for fewer rows or targets, or raise the ceiling. | | 429 `share_busy` | no | treg's account for that provider is at its limit and your team already has calls running on it. Send fewer at once, retry after `retry_after_s`, or call the routed tool. | | 429 `trial_allowance_reached` | no | A free trial pool on treg's key is used up for today; it resets at 00:00 UTC. Connect the team's own key. | | 503 `provider_capacity_unavailable` | no | treg's own account for that provider is out. Take one of the body's `alternatives`, use the team's own key, or retry after `resets_at` or a minute. | | `X-Treg-Capacity: exhausted` on any status | not when `X-Treg-Cost-Micro` is `0` | treg's own account for that tool refused for want of credit. Not your balance; try another tool. | | 502 `route_failed` | `charged_micro` in the body | Every provider of a routed call failed or missed; `tried` lists them. Misses can be billed: read `charged_micro` before running it again. | | 409, 410 with an `idempotency_*` error | see below | See "Retrying without paying twice". | Any other refusal from treg (a paused provider, treg itself busy, an answer over its size limit, an old CLI) charged nothing, and its body's `message` says what to do. ## Retrying without paying twice A failed call (a 4xx or 5xx relayed from the provider) was never billed: fix it, or try another provider. A timeout or a dropped connection on your side is different: the provider may have answered and been paid before the answer was lost. Send an `Idempotency-Key` header (`idempotency_key` over MCP) on any call you may need to repeat, and repeat it with the same key. treg returns the stored answer, does not call the provider again and charges nothing; the reply carries `X-Treg-Idempotent-Replay: true` (`replayed: true` over MCP), `X-Treg-Cost-Micro: 0`, and the first call's charge in `X-Treg-Original-Cost-Micro`. - Use a new idempotency key, or none, for new work, even with the same parameters: asking again to see what changed is a new call, and the old key would hand back the old answer. Reusing one for a different request is refused (422). - Idempotency keys belong to the caller and last 24 hours; a call that fails frees its key at once. - 409: the original call is still running; retry shortly.