treg

# treg — the tool catalog for your agent

**Ask for the task, not the tool.** When a job needs external or live data — backlinks, keyword
volume, a TikTok profile, a work email, competitor ad creative — search the catalog, read the price,
call it.

Two kinds of tool answer to the same token, through the same proxy, which injects the credential
**server-side** so you never hold it:

- **The catalog** — curated external endpoints treg can call for you.
- **Your own tools** — what a teammate registered and shared with this org: API accounts, OAuth
  connections, skills.
  Note: an X (Twitter) connection made through treg's app is metered per call (X bills the app
  owner per use); the response reports the price. A team's own X developer app is not metered.

The mechanics:

- **Endpoint:** `{BASE}`  ·  **CLI:** `treg`  ·  the CLI is a thin client over the API.
- **Auth:** every call sends `X-Treg-Token: <your token>`.
- A **tool** = an upstream base URL + credential **bindings**. A **skill/bundle** = a recipe
  (SKILL.md) + its secrets + its tool(s). The proxy *relays, never models* the upstream.

## First: install + sign in
```bash
curl -fsSL {BASE}/install.sh | sh     # installs the CLI + points it here
treg login                            # browser sign-in (GitHub / Google / email code) — first login registers you
treg login --email you@company.com    # terminal-only alternative (emailed 6-digit code)
treg login --token <per-org-token>    # non-interactive (agents/CI)
```
Everything runs in your **active org** (first login creates a personal one). Team invites arrive by
email — see them with `treg invites`, accept with `treg accept` (or `treg org join <code>`). Switch
teams: `treg org switch <slug>`.

## Already connected over MCP? Then you have the tools, not the CLI

If you reached treg through `{BASE}/mcp/` — ChatGPT, Claude Code, Cursor — the CLI steps above do not
apply to you. You have five tools: `catalog_search`, `catalog_get`, `call`, `balance`, `my_tools`.
Everything in this document maps onto them:

- "search the catalog" → `catalog_search`, then `catalog_get` for the exact price and parameters
- "call it" → `call` with the endpoint id, or `<tool-name>/<path>` for one of the team's own tools
- "check the balance" → `balance`

The rules below are the same either way. The one that matters most — **say the price before you
spend it** — matters more here, because `call` returns `cost_usd` and you can report what a call
actually cost rather than estimating.

A `call` on a catalog endpoint spends the team's balance. A `call` on one of the team's own tools
spends nothing: that key belongs to them.

## Task — the catalog: what treg can do for you (start here)

2,600+ catalogued endpoints across 60+ providers, grouped by what they DO: keyword & rank tracking,
backlinks & authority, AI visibility, trending & discovery, publishing to the team's own social
accounts, people & company enrichment, ads management & creative, measurement.

```bash
treg catalog search "subreddit posts"            # find endpoints by what they do
treg catalog get scrapecreators.reddit.subreddit.posts   # params, PRICE, how you'd be served
treg call scrapecreators.reddit.subreddit.posts --query subreddit=news
treg balance                                     # the prepaid balance + recent charges
treg catalog request "<what you need>"           # searched, not there? file it — steers what's added next
```
Notes:
- Every endpoint's price is in `treg catalog get`, before you call it.
- Discovery jobs usually have TWO shapes in the catalog — a structured one (filters: title, location,
  followers, funding) and a semantic one (describe what you want; `exa.*`). When a brief mixes hard
  limits with a fuzzy niche, run both and merge: e.g. creators = `influencersclub.creators.search`
  (filters) ∪ `exa.creators.search` (description, pinned to the platform domain); people = a
  `people.search` provider ∪ `exa.people.search`; who-holds-a-role questions = `exa.web.answer`.
- HTTP **402** = out of balance, with a machine-actionable body (`balance_micro`,
  `estimated_cost_micro`, `topup_url`). Recovery: `treg balance` → top up in the dashboard
  (Team → Billing) → or store the org's own key for that provider (own keys are never billed
  to the balance — they take priority automatically).
- HTTP **503** `provider_capacity_unavailable` = treg's own account for that provider is out
  (not your balance; nothing charged). Body has `resets_at` and `alternatives` (same capability,
  other providers) — choose one, or use your own key. treg never switches providers for you.
- An org tool or secret for the provider always wins over treg's key, automatically — the catalog
  is the fallback, not a replacement for keys the team already has.
- **Choosing between providers of one capability — the procedure.** `treg catalog get <id>` lists
  every provider serving the same job with `COST`, `WORKS` (success rate treg has observed, with the
  sample size), `SPEED` (median) and `LAST OK`. Work down this order:
  1. **Match the inputs you actually HAVE.** An endpoint wanting a `profile_url` is not a substitute
     when you hold a name and a domain, whatever it costs. This rule outranks price every time.
  2. Then **reliability**: a high `WORKS` with a real sample beats a rounder number with a tiny one —
     `99% (121)` is stronger evidence than `100% (8)`.
  3. Then **price**. Spreads inside one capability 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 it and nobody has called
     it — prefer almost anything else.
  - **If a call fails with 429 / 5xx / a timeout, try the next provider.** You know its parameters,
    so you can build its request. Say which one you switched to.
  - **Never retry a 4xx elsewhere.** A 4xx is usually your parameters; fixing them is the